Documentation markup for large projects
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Pretty documentation generator for large projects


JDoc is a Jekyll plugin that lets you organize your documentation into a hierarchical file structure. It was created primarily to generate Project Pages for large projects where the documentation needs to be organized hierarchically across multiple files.

For example, this code produces this result.

Getting Started

  1. Install jekyll
  2. Clone jdoc-example recursively to include its submodule:
    git clone --recursive git://
  3. Start jekyll using jekyll --server (read more) and see the site here
  4. Edit the files in documentation/ to start documenting!


  • You might want to use jekyll --server --auto to automatically regenerate the site when you modify files.
  • You can change the root URL of the site with the baseurl value in _config.yml.

File Structure

Documentation is organized in the documentation directory in root Jekyll directory. The file structure looks like this:


This structure will be rendered into a hierarchical menu. is the content that's shown for first_topic.

_sort.yml is optional. If it's included in a directory, it specifies the order in which that directory's topics are rendered in the menu. In the example above, it might look like this:


Documentation Syntax

Each file behaves just like a Jekyll file does, except that the YAML header isn't required. An initial --- is required, though:

Here's some documentation on this topic.

The title is inferred from the file's name, but you can explicitly set the title using the YAML header

title: My Custom Title
Here's some documentation on this topic.



Creates a link to another topic. The first argument is the path to the topic; the second is the text:

{% doc_link first_topic My custom text %}

<a href="/first_topic/">My custom text</a>

If the second argument is omitted, the title of the topic will be used:

{% doc_link first_topic/second_subtopic %}

<a href="/first_topic/second_subtopic/">Second Subtopic</a>


Renders all of the current topic's children in a single page. Here's an example of the output.

{% doc_children %}


Renders the hierarchical menu of topics.

{% doc_menu %}