├── .github ├── dependabot.yml └── workflows │ ├── ci.yml │ └── pages.yml ├── .gitignore ├── Gemfile ├── Gemfile.lock ├── LICENSE ├── README.md ├── _config.yml └── index.md /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: bundler 4 | directory: / 5 | schedule: 6 | interval: daily 7 | allow: 8 | - dependency-type: direct 9 | - package-ecosystem: "github-actions" 10 | directory: "/" 11 | schedule: 12 | interval: daily 13 | time: "10:00" 14 | open-pull-requests-limit: 10 15 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: ["main"] 6 | pull_request: 7 | 8 | jobs: 9 | # Build job 10 | build: 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Checkout 14 | uses: actions/checkout@v4 15 | - name: Setup Ruby 16 | uses: ruby/setup-ruby@v1 17 | with: 18 | ruby-version: '3.3' # Not needed with a .ruby-version file 19 | bundler-cache: true # runs 'bundle install' and caches installed gems automatically 20 | cache-version: 0 # Increment this number if you need to re-download cached gems 21 | - name: Build with Jekyll 22 | run: bundle exec jekyll build 23 | -------------------------------------------------------------------------------- /.github/workflows/pages.yml: -------------------------------------------------------------------------------- 1 | # This workflow uses actions that are not certified by GitHub. 2 | # They are provided by a third-party and are governed by 3 | # separate terms of service, privacy policy, and support 4 | # documentation. 5 | 6 | # Sample workflow for building and deploying a Jekyll site to GitHub Pages 7 | name: Deploy Jekyll site to Pages 8 | 9 | on: 10 | push: 11 | branches: ["main"] 12 | 13 | # Allows you to run this workflow manually from the Actions tab 14 | workflow_dispatch: 15 | 16 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 17 | permissions: 18 | contents: read 19 | pages: write 20 | id-token: write 21 | 22 | # Allow one concurrent deployment 23 | concurrency: 24 | group: "pages" 25 | cancel-in-progress: true 26 | 27 | jobs: 28 | # Build job 29 | build: 30 | runs-on: ubuntu-latest 31 | steps: 32 | - name: Checkout 33 | uses: actions/checkout@v4 34 | - name: Setup Ruby 35 | uses: ruby/setup-ruby@v1 36 | with: 37 | ruby-version: '3.3' # Not needed with a .ruby-version file 38 | bundler-cache: true # runs 'bundle install' and caches installed gems automatically 39 | cache-version: 0 # Increment this number if you need to re-download cached gems 40 | - name: Setup Pages 41 | id: pages 42 | uses: actions/configure-pages@v5 43 | - name: Build with Jekyll 44 | # Outputs to the './_site' directory by default 45 | run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" 46 | env: 47 | JEKYLL_ENV: production 48 | - name: Upload artifact 49 | # Automatically uploads an artifact from the './_site' directory by default 50 | uses: actions/upload-pages-artifact@v3 51 | 52 | # Deployment job 53 | deploy: 54 | environment: 55 | name: github-pages 56 | url: ${{ steps.deployment.outputs.page_url }} 57 | runs-on: ubuntu-latest 58 | needs: build 59 | steps: 60 | - name: Deploy to GitHub Pages 61 | id: deployment 62 | uses: actions/deploy-pages@v4 63 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Not sure what a .gitignore is? 2 | # See: https://git-scm.com/docs/gitignore 3 | 4 | # These are directly copied from Jekyll's first-party docs on `.gitignore` files: 5 | # https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control 6 | 7 | # Ignore the default location of the built site, and caches and metadata generated by Jekyll 8 | _site/ 9 | .sass-cache/ 10 | .jekyll-cache/ 11 | .jekyll-metadata 12 | 13 | # Ignore folders generated by Bundler 14 | .bundle/ 15 | vendor/ 16 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | gem "jekyll", "~> 4.4.1" # installed by `gem jekyll` 4 | # gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2 5 | 6 | gem "just-the-docs", "0.10.1" # pinned to the current release 7 | # gem "just-the-docs" # always download the latest release 8 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | addressable (2.8.7) 5 | public_suffix (>= 2.0.2, < 7.0) 6 | base64 (0.2.0) 7 | bigdecimal (3.1.9) 8 | colorator (1.1.0) 9 | concurrent-ruby (1.3.5) 10 | csv (3.3.2) 11 | em-websocket (0.5.3) 12 | eventmachine (>= 0.12.9) 13 | http_parser.rb (~> 0) 14 | eventmachine (1.2.7) 15 | ffi (1.17.1-arm64-darwin) 16 | ffi (1.17.1-x86_64-linux-gnu) 17 | forwardable-extended (2.6.0) 18 | google-protobuf (4.29.3-arm64-darwin) 19 | bigdecimal 20 | rake (>= 13) 21 | google-protobuf (4.29.3-x86_64-linux) 22 | bigdecimal 23 | rake (>= 13) 24 | http_parser.rb (0.8.0) 25 | i18n (1.14.7) 26 | concurrent-ruby (~> 1.0) 27 | jekyll (4.4.1) 28 | addressable (~> 2.4) 29 | base64 (~> 0.2) 30 | colorator (~> 1.0) 31 | csv (~> 3.0) 32 | em-websocket (~> 0.5) 33 | i18n (~> 1.0) 34 | jekyll-sass-converter (>= 2.0, < 4.0) 35 | jekyll-watch (~> 2.0) 36 | json (~> 2.6) 37 | kramdown (~> 2.3, >= 2.3.1) 38 | kramdown-parser-gfm (~> 1.0) 39 | liquid (~> 4.0) 40 | mercenary (~> 0.3, >= 0.3.6) 41 | pathutil (~> 0.9) 42 | rouge (>= 3.0, < 5.0) 43 | safe_yaml (~> 1.0) 44 | terminal-table (>= 1.8, < 4.0) 45 | webrick (~> 1.7) 46 | jekyll-include-cache (0.2.1) 47 | jekyll (>= 3.7, < 5.0) 48 | jekyll-sass-converter (3.0.0) 49 | sass-embedded (~> 1.54) 50 | jekyll-seo-tag (2.8.0) 51 | jekyll (>= 3.8, < 5.0) 52 | jekyll-watch (2.2.1) 53 | listen (~> 3.0) 54 | json (2.9.1) 55 | just-the-docs (0.10.1) 56 | jekyll (>= 3.8.5) 57 | jekyll-include-cache 58 | jekyll-seo-tag (>= 2.0) 59 | rake (>= 12.3.1) 60 | kramdown (2.5.1) 61 | rexml (>= 3.3.9) 62 | kramdown-parser-gfm (1.1.0) 63 | kramdown (~> 2.0) 64 | liquid (4.0.4) 65 | listen (3.9.0) 66 | rb-fsevent (~> 0.10, >= 0.10.3) 67 | rb-inotify (~> 0.9, >= 0.9.10) 68 | mercenary (0.4.0) 69 | pathutil (0.16.2) 70 | forwardable-extended (~> 2.6) 71 | public_suffix (6.0.1) 72 | rake (13.2.1) 73 | rb-fsevent (0.11.2) 74 | rb-inotify (0.11.1) 75 | ffi (~> 1.0) 76 | rexml (3.4.0) 77 | rouge (4.5.1) 78 | safe_yaml (1.0.5) 79 | sass-embedded (1.83.4-arm64-darwin) 80 | google-protobuf (~> 4.29) 81 | sass-embedded (1.83.4-x86_64-linux-gnu) 82 | google-protobuf (~> 4.29) 83 | terminal-table (3.0.2) 84 | unicode-display_width (>= 1.1.1, < 3) 85 | unicode-display_width (2.6.0) 86 | webrick (1.9.1) 87 | 88 | PLATFORMS 89 | arm64-darwin 90 | x86_64-linux-gnu 91 | 92 | DEPENDENCIES 93 | jekyll (~> 4.4.1) 94 | just-the-docs (= 0.10.1) 95 | 96 | BUNDLED WITH 97 | 2.5.9 98 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 just-the-docs 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # just-the-docs-template 2 | 3 | This is a *bare-minimum* template to create a [Jekyll] site that: 4 | 5 | - uses the [Just the Docs] theme; 6 | - can be built and published on [GitHub Pages]; 7 | - can be built and previewed locally, and published on other platforms. 8 | 9 | More specifically, the created site: 10 | 11 | - uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem; 12 | - uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages. 13 | 14 | To get started with creating a site, simply: 15 | 16 | 1. click "[use this template]" to create a GitHub repository 17 | 2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions 18 | 19 | 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](#hosting-your-docs-from-an-existing-project-repo). 20 | 21 | After completing the creation of your new site on GitHub, update it as needed: 22 | 23 | ## Replace the content of the template pages 24 | 25 | Update the following files to your own content: 26 | 27 | - `index.md` (your new home page) 28 | - `README.md` (information for those who access your site repo on GitHub) 29 | 30 | ## Changing the version of the theme and/or Jekyll 31 | 32 | Simply edit the relevant line(s) in the `Gemfile`. 33 | 34 | ## Adding a plugin 35 | 36 | The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin. 37 | 38 | To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]: 39 | 40 | - Add the following to your site's `Gemfile`: 41 | 42 | ```ruby 43 | gem "jekyll-default-layout" 44 | ``` 45 | 46 | - And add the following to your site's `_config.yml`: 47 | 48 | ```yaml 49 | plugins: 50 | - jekyll-default-layout 51 | ``` 52 | 53 | Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`. 54 | 55 | ## Publishing your site on GitHub Pages 56 | 57 | 1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to: 58 | 59 | ```yaml 60 | title: YOUR TITLE 61 | description: YOUR DESCRIPTION 62 | theme: just-the-docs 63 | 64 | url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME 65 | 66 | aux_links: # remove if you don't want this link to appear on your pages 67 | Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME 68 | ``` 69 | 70 | 2. Push your updated `_config.yml` to your site on GitHub. 71 | 72 | 3. In your newly created repo on GitHub: 73 | - go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`. 74 | - if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`. 75 | 76 | ## Building and previewing your site locally 77 | 78 | Assuming [Jekyll] and [Bundler] are installed on your computer: 79 | 80 | 1. Change your working directory to the root directory of your site. 81 | 82 | 2. Run `bundle install`. 83 | 84 | 3. Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`. 85 | 86 | The built site is stored in the directory `_site`. 87 | 88 | ## Publishing your built site on a different platform 89 | 90 | Just upload all the files in the directory `_site`. 91 | 92 | ## Customization 93 | 94 | You're free to customize sites that you create with this template, however you like! 95 | 96 | [Browse our documentation][Just the Docs] to learn more about how to use this theme. 97 | 98 | ## Hosting your docs from an existing project repo 99 | 100 | You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the [just-the-docs template](https://github.com/just-the-docs/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. 101 | 102 | ### Copy the template files 103 | 104 | 1. Create a `.github/workflows` directory at your project root if your repo doesn't already have one. Copy the `pages.yml` file into this directory. GitHub Actions searches this directory for workflow files. 105 | 106 | 2. Create a `docs` directory at your project root and copy all remaining template files into this directory. 107 | 108 | ### Modify the GitHub Actions workflow 109 | 110 | 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. 111 | 112 | 1. Set the default `working-directory` param for the build job. 113 | 114 | ```yaml 115 | build: 116 | runs-on: ubuntu-latest 117 | defaults: 118 | run: 119 | working-directory: docs 120 | ``` 121 | 122 | 2. Set the `working-directory` param for the Setup Ruby step. 123 | 124 | ```yaml 125 | - name: Setup Ruby 126 | uses: ruby/setup-ruby@v1 127 | with: 128 | ruby-version: '3.3' 129 | bundler-cache: true 130 | cache-version: 0 131 | working-directory: '${{ github.workspace }}/docs' 132 | ``` 133 | 134 | 3. Set the path param for the Upload artifact step: 135 | 136 | ```yaml 137 | - name: Upload artifact 138 | uses: actions/upload-pages-artifact@v3 139 | with: 140 | path: docs/_site/ 141 | ``` 142 | 143 | 4. Modify the trigger so that only changes within the `docs` directory 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. 144 | 145 | ```yaml 146 | on: 147 | push: 148 | branches: 149 | - "main" 150 | paths: 151 | - "docs/**" 152 | ``` 153 | 154 | ## Licensing and Attribution 155 | 156 | 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! 157 | 158 | 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]. 159 | 160 | ---- 161 | 162 | [^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). 163 | 164 | [Jekyll]: https://jekyllrb.com 165 | [Just the Docs]: https://just-the-docs.github.io/just-the-docs/ 166 | [GitHub Pages]: https://docs.github.com/en/pages 167 | [GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ 168 | [Bundler]: https://bundler.io 169 | [use this template]: https://github.com/just-the-docs/just-the-docs-template/generate 170 | [`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout 171 | [`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag 172 | [MIT License]: https://en.wikipedia.org/wiki/MIT_License 173 | [starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml 174 | [actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE 175 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | title: Just the Docs Template 2 | description: A starter template for a Jeykll site using the Just the Docs theme! 3 | theme: just-the-docs 4 | 5 | url: https://just-the-docs.github.io 6 | 7 | aux_links: 8 | Template Repository: https://github.com/just-the-docs/just-the-docs-template 9 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Home 3 | layout: home 4 | --- 5 | 6 | This is a *bare-minimum* template to create a Jekyll site that uses the [Just the Docs] theme. You can easily set the created site to be published on [GitHub Pages] – the [README] file explains how to do that, along with other details. 7 | 8 | If [Jekyll] is installed on your computer, you can also build and preview the created site *locally*. This lets you test changes before committing them, and avoids waiting for GitHub Pages.[^1] And you will be able to deploy your local build to a different platform than GitHub Pages. 9 | 10 | More specifically, the created site: 11 | 12 | - uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem 13 | - uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages 14 | 15 | Other than that, you're free to customize sites that you create with this template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins. 16 | 17 | [Browse our documentation][Just the Docs] to learn more about how to use this theme. 18 | 19 | To get started with creating a site, simply: 20 | 21 | 1. click "[use this template]" to create a GitHub repository 22 | 2. go to Settings > Pages > Build and deployment > Source, and select GitHub Actions 23 | 24 | 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](https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md#hosting-your-docs-from-an-existing-project-repo) in the template README. 25 | 26 | ---- 27 | 28 | [^1]: [It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll#creating-your-site). 29 | 30 | [Just the Docs]: https://just-the-docs.github.io/just-the-docs/ 31 | [GitHub Pages]: https://docs.github.com/en/pages 32 | [README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md 33 | [Jekyll]: https://jekyllrb.com 34 | [GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/ 35 | [use this template]: https://github.com/just-the-docs/just-the-docs-template/generate 36 | --------------------------------------------------------------------------------