Guides for SE student projects »

Using Jekyll for project documentation

Jekyll is a popular tool for generating static websites from markdown-like text.

Given below are some information useful for when you want to update documentation in a project that uses Jekyll.

Setting up GitHub Pages for Jekyll

As GitHub has native support for Jekyll, it can convert your documentation into HTML and deploy it on the github.io URL of your project.

Do the following to set up the GitHub Pages website of your project:

  1. Go to your repo's settings tab.
  2. Click   Pages  on the menu on the left edge of page.
  3. Set the Source as:  Deploy from a branch branch master branch and /docs folder (assuming project documentation is in that folder) and click  Save .

The project website will be available at https://{your_org}.github.io/{your_repo} the next time the master branch is updated. Example: https://myorg.github.io/myrepo

Updating documents

Jekyll uses kramdown (a superset of Markdown) for writing content. You can use Intellij (or any other text editor) to update the relevant .md files.

Recommendation: Limit your content to Markdown and GFMD syntax only i.e., avoid kramdown-specific syntax that are not compatible with Markdown/GFMD

Recommendation: Enable soft-wrapping in your code editor for *.md files. For example, as explained in Intellij IDEA: Useful settings guide.

  • Previewing changes locally: There are several ways to preview changes locally.
    • Option 1 -- Intellij preview: Intellij supports previewing Markdown files, as explained here. While the preview shown by Intellij is somewhat rudimentary, it is good enough for most cases.
    • Option 2 -- Run Jekyll locally: You can set up Jekyll locally and run it to see the exact way the update affects the final outcome.
  • Previewing changes on GitHub:
    • Option 1 -- GitHub preview: You can see a basic preview of the page by navigating to the corresponding .md source file in GitHub.
    • Option 2 -- Use Netlify PR preview: You can set up Netlify to show previews of PRs (to learn how, read the Using Netlify guide). This method shows a preview of the exact way the update affects the final outcome.

Site-wide settings

  • Typically, the _config.yml file specifies project-specific site-wide settings.
    An example is the title property, which defines the title of your site, usually the name of your project.

  • The files in docs/_include and docs/_layouts control the template of the pages; the files in docs/_sass control the style of the pages.

    Caution: Modifying these files requires some knowledge and experience with Jekyll. You should only modify them (at your own risk) if you need greater control over the site’s layout.