just-the-docs-template

This is a bare-minimum template to create a Jekyll site that:

• uses the Just the Docs theme;
• can be built and published on GitHub Pages;
• can be built and previewed locally, and published on other platforms.

More specifically, the created site:

• uses a gem-based approach, i.e. uses a Gemfile and loads the just-the-docs gem;
• uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages.

To get started with creating a site, just click "use this template"!

After completing the creation of your new site on GitHub, update it as needed:

Replace the content of the template pages

Update the following files to your own content:

• index.md (your new home page)
• README.md (information for those who access your site repo on GitHub)

Changing the version of the theme and/or Jekyll

Simply edit the relevant line(s) in the Gemfile.

Adding a plugin

The Just the Docs theme automatically includes the jekyll-seo-tag plugin.

To add an extra plugin, you need to add it in the Gemfile and in _config.yml. For example, to add jekyll-default-layout:

• Add the following to your site's Gemfile:

  gem "jekyll-default-layout"
  

• And add the following to your site's _config.yml:

  plugins:
    - jekyll-default-layout
  

Note: If you are using a Jekyll version less than 3.5.0, use the gems key instead of plugins.

Publishing your site on GitHub Pages

1. If your created site is YOUR-USERNAME/YOUR-SITE-NAME, update _config.yml to:

   title: YOUR TITLE
   description: YOUR DESCRIPTION
   theme: just-the-docs
   
   url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME
   
   aux_links: # remove if you don't want this link to appear on your pages
     Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME
   

2. Push your updated _config.yml to your site on GitHub.

3. In your newly created repo on GitHub:

   • go to the Settings tab -> Pages -> Build and deployment, then select Source: GitHub Actions.
   • if there were any failed Actions, go to the Actions tab and click on Re-run jobs.

Building and previewing your site locally

Assuming Jekyll and Bundler are installed on your computer:

1. Change your working directory to the root directory of your site.

2. Run bundle install.

3. Run bundle exec jekyll serve to build your site and preview it at localhost:4000.

   The built site is stored in the directory _site.

Publishing your built site on a different platform

Just upload all the files in the directory _site.

Customization

You're free to customize sites that you create with this template, however you like!

Browse our documentation to learn more about how to use this theme.

[^1]: It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub.