If you're familiar with Grunt, you can easily generate .html docs with grunt-jsdoc.
- Document your code with JSDoc.
- Use grunt-jsdoc which internally uses jsdoc to generate code documentation.
- This will also output the source code in HTML and within the documentation it will include links to code lines for each publicly accessible member.
- You can also have control on the links by simply using the
@link directive of JSDoc:
See {@link https://github.com/onury|My GitHub Profile}.
See a Gruntfile example below.
Note that this supports all JSDoc CLI options.
grunt.initConfig({
'jsdoc': {
dist: {
src: ['./src/core/mylib.js'],
options: {
destination: './doc/html'
}
}
}
});
And you run this task with grunt jsdoc. Or you can add the grunt-contrib-watch plugin to auto-run each time the file changes.
Templates and Styling:
- You can always play with the CSS file and overwrite it for your own taste.
- Or you can use docstrap template for JSDoc3 based on Bootstrap which can be used with
grunt-jsdoc.
Using Jekyll for documentation:
Although it's natively supported, you do not have to use Jekyll for GitHub Pages. Jekyll is actually designed for static websites or blogs. But it can take markdown files. So, I'd first create github flavoured markdown files from code via jsdoc-to-markdown (there is also a Grunt plugin grunt-jsdoc2md) then configure a Jekyll project accordingly.
But note that you'll need to do some extra work to install and configure Jekyll. Here is a good article and a sample project to start with.
UPDATE:
After answering this, I started working on a tool for building documentation easily. Now, it's mature enough to post here and see if you like it. It's called Docma.
Key Docma features are; it can both parse JSDoc and Markdown files into HTML documentation, generates a web-app, extremely configurable and works great with Github Pages.
See Docma documentation here, which is also built with Docma and hosted on GitHub Pages.
A sample screenshot of Docma generated SPA:
