Debian Codegraph @

site/README.md

raw
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, just click "[use this template]"!
15
16 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).
17
18 After completing the creation of your new site on GitHub, update it as needed:
19
20 ## Replace the content of the template pages
21
22 Update the following files to your own content:
23
24 - `index.md` (your new home page)
25 - `README.md` (information for those who access your site repo on GitHub)
26
27 ## Changing the version of the theme and/or Jekyll
28
29 Simply edit the relevant line(s) in the `Gemfile`.
30
31 ## Adding a plugin
32
33 The Just the Docs theme automatically includes the [`jekyll-seo-tag`] plugin.
34
35 To add an extra plugin, you need to add it in the `Gemfile` *and* in `_config.yml`. For example, to add [`jekyll-default-layout`]:
36
37 - Add the following to your site's `Gemfile`:
38
39 ```ruby
40 gem "jekyll-default-layout"
41 ```
42
43 - And add the following to your site's `_config.yml`:
44
45 ```yaml
46 plugins:
47 - jekyll-default-layout
48 ```
49
50 Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
51
52 ## Publishing your site on GitHub Pages
53
54 1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to:
55
56 ```yaml
57 title: YOUR TITLE
58 description: YOUR DESCRIPTION
59 theme: just-the-docs
60
61 url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME
62
63 aux_links: # remove if you don't want this link to appear on your pages
64 Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME
65 ```
66
67 2. Push your updated `_config.yml` to your site on GitHub.
68
69 3. In your newly created repo on GitHub:
70 - go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`.
71 - if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`.
72
73 ## Building and previewing your site locally
74
75 Assuming [Jekyll] and [Bundler] are installed on your computer:
76
77 1. Change your working directory to the root directory of your site.
78
79 2. Run `bundle install`.
80
81 3. Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`.
82
83 The built site is stored in the directory `_site`.
84
85 ## Publishing your built site on a different platform
86
87 Just upload all the files in the directory `_site`.
88
89 ## Customization
90
91 You're free to customize sites that you create with this template, however you like!
92
93 [Browse our documentation][Just the Docs] to learn more about how to use this theme.
94
95 ## Hosting your docs from an existing project repo
96
97 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.
98
99 ### Copy the template files
100
101 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.
102
103 2. Create a `docs` directory at your project root and copy all remaining template files into this directory.
104
105 ### Modify the Github Actions worklow
106
107 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.
108
109 1. Set the default `working-directory` param for the build job.
110
111 ```yaml
112 build:
113 runs-on: ubuntu-latest
114 defaults:
115 run:
116 working-directory: docs
117 ```
118
119 2. Set the `working-directory` param for the Setup Ruby step.
120
121 ```yaml
122 - name: Setup Ruby
123 uses: ruby/setup-ruby@v1
124 with:
125 ruby-version: '3.1'
126 bundler-cache: true
127 cache-version: 0
128 working-directory: '${{ github.workspace }}/docs'
129 ```
130
131 3. Set the path param for the Upload artifact step:
132
133 ```yaml
134 - name: Upload artifact
135 uses: actions/upload-pages-artifact@v1
136 with:
137 path: "docs/_site/"
138 ```
139
140 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.
141
142 ```yaml
143 on:
144 push:
145 branches:
146 - "main"
147 paths:
148 - "docs/**"
149 ```
150
151 ## Licensing and Attribution
152
153 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!
154
155 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].
156
157 ----
158
159 [^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).
160
161 [Jekyll]: https://jekyllrb.com
162 [Just the Docs]: https://just-the-docs.github.io/just-the-docs/
163 [GitHub Pages]: https://docs.github.com/en/pages
164 [GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
165 [Bundler]: https://bundler.io
166 [use this template]: https://github.com/just-the-docs/just-the-docs-template/generate
167 [`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout
168 [`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag
169 [MIT License]: https://en.wikipedia.org/wiki/MIT_License
170 [starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml
171 [actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE