Overview

The Just the Docs template is a bare-minimum template to create a Jekyll site. It uses the Just the Docs theme and can be built and published on GitHub Pages. The site can also be built and previewed locally, and published on other platforms. It uses a gem-based approach and the GitHub Pages/Actions workflow to build and publish the site on GitHub Pages.

Features

• Uses the Just the Docs theme
• Can be built and published on GitHub Pages
• Can be built and previewed locally
• Can be published on other platforms

Installation

To get started with creating a site:

1. Click “use this template” on the GitHub repository.
2. If you want to maintain your docs in the docs directory of an existing project repo:
   • See “Hosting your docs from an existing project repo” in the documentation.

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

1. Replace the content of the template pages.
2. 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)

To change the version of the theme and/or Jekyll:

1. Edit the relevant line(s) in the Gemfile.

To add a plugin:

1. Add it in the Gemfile.
2. Add it in _config.yml. For example, to add jekyll-default-layout:
   • Add the following to your site’s Gemfile:

   gem 'jekyll-default-layout'
   

   • Add the following to your site’s _config.yml:

   plugins:
     - jekyll-default-layout
   

To publish your site on GitHub Pages:

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

   baseurl: '/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.
4. If there were any failed Actions, go to the Actions tab and click on Re-run jobs.

To build and preview your site locally:

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.
4. The built site is stored in the directory _site.

To publish your built site on a different platform:

1. Upload all the files in the directory _site.

Summary

The Just the Docs template is a versatile solution for creating Jekyll sites. It provides easy installation and customization options, and allows for seamless publishing on GitHub Pages and other platforms. With its gem-based approach and GitHub Pages/Actions workflow integration, building, previewing, and publishing sites becomes a streamlined process.