Skip to content

Latest commit

 

History

History
103 lines (63 loc) · 3.43 KB

README.md

File metadata and controls

103 lines (63 loc) · 3.43 KB
Raw

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.