|
1 | | -# crup |
2 | | -Codebase Ramp Up Program (CRUP) for New Members! |
| 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.1' |
| 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@v1 |
| 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 |
0 commit comments