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
Gemfileand loads thejust-the-docsgem; - uses the GitHub Pages / Actions workflow to build and publish the site on GitHub Pages.
To get started with creating a site, simply:
- click "use this template" to create a GitHub repository
- go to Settings > Pages > Build and deployment > Source, and select GitHub Actions
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.
After completing the creation of your new site on GitHub, update it as needed:
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)
Simply edit the relevant line(s) in the Gemfile.
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.
-
If your created site is
YOUR-USERNAME/YOUR-SITE-NAME, update_config.ymlto: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
-
Push your updated
_config.ymlto your site on GitHub. -
In your newly created repo on GitHub:
- go to the
Settingstab ->Pages->Build and deployment, then selectSource:GitHub Actions. - if there were any failed Actions, go to the
Actionstab and click onRe-run jobs.
- go to the
Assuming Jekyll and Bundler are installed on your computer:
-
Change your working directory to the root directory of your site.
-
Run
bundle install. -
Run
bundle exec jekyll serveto build your site and preview it atlocalhost:4000.The built site is stored in the directory
_site.
Just upload all the files in the directory _site.
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.
You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the just-the-docs template, you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a docs directory. You can clone the template to your local machine or download the .zip file to access the files.
-
Create a
.github/workflowsdirectory at your project root if your repo doesn't already have one. Copy thepages.ymlfile into this directory. GitHub Actions searches this directory for workflow files. -
Create a
docsdirectory at your project root and copy all remaining template files into this directory.
The GitHub Actions workflow that builds and deploys your site to Github Pages is defined by the pages.yml file. You'll need to edit this file to that so that your build and deploy steps look to your docs directory, rather than the project root.
-
Set the default
working-directoryparam for the build job.build: runs-on: ubuntu-latest defaults: run: working-directory: docs
-
Set the
working-directoryparam for the Setup Ruby step.- name: Setup Ruby uses: ruby/setup-ruby@v1 with: ruby-version: '3.1' bundler-cache: true cache-version: 0 working-directory: '${{ github.workspace }}/docs'
-
Set the path param for the Upload artifact step:
- name: Upload artifact uses: actions/upload-pages-artifact@v1 with: path: "docs/_site/"
-
Modify the trigger so that only changes within the
docsdirectory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy.on: push: branches: - "main" paths: - "docs/**"
This repository is licensed under the MIT License. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!
The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party starter workflows. A copy of their MIT License is available in actions/starter-workflows.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent