Skip to content

Commit aeefd10

Browse files
chipspeakchipspeak
authored
Merge pull request #31 from chipspeak/GUIDEFRAME-46
task(GUIDEFRAME-46): create github pages docs site
2 parents 65f1bd4 + 0e7069f commit aeefd10

9 files changed

Lines changed: 410 additions & 1 deletion

File tree

‎.DS_Store‎

-4 KB
Binary file not shown.

‎.github/workflows/pages.yaml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
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:
12+
- "main"
13+
paths:
14+
- "docs/**"
15+
16+
# Allows you to run this workflow manually from the Actions tab
17+
workflow_dispatch:
18+
19+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
20+
permissions:
21+
contents: read
22+
pages: write
23+
id-token: write
24+
25+
# Allow one concurrent deployment
26+
concurrency:
27+
group: "pages"
28+
cancel-in-progress: true
29+
30+
jobs:
31+
# Build job
32+
build:
33+
runs-on: ubuntu-latest
34+
steps:
35+
- name: Checkout
36+
uses: actions/checkout@v4
37+
- name: Setup Ruby
38+
uses: ruby/setup-ruby@v1
39+
with:
40+
ruby-version: '3.3' # Not needed with a .ruby-version file
41+
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
42+
cache-version: 0 # Increment this number if you need to re-download cached gems
43+
woking-directory: '${{ github.workspace }}/docs'
44+
- name: Setup Pages
45+
id: pages
46+
uses: actions/configure-pages@v5
47+
- name: Build with Jekyll
48+
# Outputs to the './_site' directory by default
49+
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
50+
env:
51+
JEKYLL_ENV: production
52+
- name: Upload artifact
53+
# Automatically uploads an artifact from the './_site' directory by default
54+
uses: actions/upload-pages-artifact@v3
55+
with: docs/_site/
56+
57+
# Deployment job
58+
deploy:
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
runs-on: ubuntu-latest
63+
needs: build
64+
steps:
65+
- name: Deploy to GitHub Pages
66+
id: deployment
67+
uses: actions/deploy-pages@v4

‎docs/Gemfile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
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

‎docs/Gemfile.lock‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
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

‎docs/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
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.

‎docs/README.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
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

‎docs/_config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
title: GuideFrame Docs
2+
description: The official documentation for GuideFrame.
3+
theme: just-the-docs
4+
5+
url: https://chipspeak.github.io/guideframe
6+
7+
aux_links:
8+
Template Repository: https://github.com/chipspeak/guideframe

0 commit comments

Comments
 (0)