Embed API docs (jsdoc) generated site

dkebler commented 6 years ago

Feature request

Asked about it here. Solved my own question. https://forum.vuejs.org/t/solved-vuepress-embedd-api-docs-in-vuepress-site/41080/4

What problem does this feature solve?

allows API docs site generated by another project (i.e. jsdoc) to be embeded into vuepress. Currently API docs can only be linked externally and appear on a new tab. This allows them to appear below the navbar replacing the sidebar/page components when active (in the same way Home component does) in a seamless way. In the future vuepress might have built a custom jsdoc theme to better integrate but this works for now.

What does the proposed API look like?

no API just a new component in the default theme

here is it live in an s3 bucket http://guide.ucommandit.net.s3-website-us-west-2.amazonaws.com/

the above show API docs embeded with the docstrap jsdoc template using the slate bootswatch theme. I had to modify the docstrap template to set a base url of api in the so that I could send the output of the generator to ./vuepress/public/api folder and make this all work.

How should this be implemented in your opinion?

user creates a page in the same way home page is done with frontmatter key

---
api: true
staticDir: api # if using .vuepress/public static directory must match base URL set in your generated API template <head> section
defaultPage: Base # api page to load first, default is just '/'
# url: 'https://dkebler.github.io/landingpage-guide/' # if set will embed external site instead of api site in .vuepress/public
# any page content below is ignored
---
this is ignored

then layout component just add a v-if for add a API component if api:true just like home page API component uses <object> tag to embed the content found in the set api 'static' folder

Are you willing to work on this yourself?**

already done, just wanting some feedback before bothering to make a pull request https://github.com/dkebler/vuepress/tree/api/lib/default-theme

BTW what I have done is not limited to API docs. Any site can be embedded whether external or in a static fold. I suppose this could be made generic if desired instead of specific to API docs generated site.

jebkor commented 6 years ago

Hello @dkebler, running the chance of getting ban-hammered, not saying anything useful, I would like to ask you, how did you manage to get the navbar to show on the API page? I am having the same needs as you have right here and managed to reverse-engineer my way to somehow do it, but the Vuepress navbar is not showing. Can you perhaps make a short step-by-step guide to follow? API.vue is created and the layout.vue is modified.

Any help would be appreciated.

armano2 commented 5 years ago

@dkebler i'm surprised that you are not using https://github.com/jsdoc2md/jsdoc-to-markdown and injecting it directly to vuepress

vuejs / vuepress