Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Embed API docs (jsdoc) generated site #769

Open
dkebler opened this issue Aug 26, 2018 · 2 comments
Open

Embed API docs (jsdoc) generated site #769

dkebler opened this issue Aug 26, 2018 · 2 comments
Labels
topic: theme Relates to VuePress theme type: feature request Request to add a new feature

Comments

@dkebler
Copy link

dkebler commented Aug 26, 2018 •
edited
Loading

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/

image

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.
@ulivz ulivz added topic: theme Relates to VuePress theme type: feature request Request to add a new feature labels Aug 29, 2018
@jebkor
Copy link

jebkor commented Aug 30, 2018

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
Copy link

armano2 commented Nov 18, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
topic: theme Relates to VuePress theme type: feature request Request to add a new feature
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@armano2 @dkebler @jebkor @ulivz