h3n3/endorphin
1
0
Fork 0
Code Issues 8 Pull Requests 1 Packages Projects Releases Wiki Activity

Add just-the-docs template

Browse Source
This commit is contained in:
Kevin
2023-04-20 21:08:06 -04:00
parent d4989853d4
commit e89439f830
8 changed files with 386 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
.github/workflows/pages.yml vendored Normal file
View File

@@ -0,0 +1,62 @@
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
name: Deploy Jekyll site to Pages
on:
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.1' # Not needed with a .ruby-version file
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
cache-version: 0 # Increment this number if you need to re-download cached gems
- name: Setup Pages
id: pages
uses: actions/configure-pages@v2
- name: Build with Jekyll
# Outputs to the './_site' directory by default
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
env:
JEKYLL_ENV: production
- name: Upload artifact
# Automatically uploads an artifact from the './_site' directory by default
uses: actions/upload-pages-artifact@v1
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1

6
.gitignore vendored
View File

@@ -1,4 +1,10 @@
# Copied from https://github.com/github/gitignore/blob/main/Jekyll.gitignore
# Ignore metadata generated by Jekyll
_site/ _site/
.sass-cache/ .sass-cache/
.jekyll-cache/ .jekyll-cache/
.jekyll-metadata .jekyll-metadata
# Ignore folders generated by Bundler
.bundle/
vendor/

7
Gemfile Normal file
View File

@@ -0,0 +1,7 @@
source 'https://rubygems.org'
gem "jekyll", "~> 4.3" # installed by `gem jekyll`
# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2
gem "just-the-docs", "0.5.0" # pinned to the current release
# gem "just-the-docs" # always download the latest release

79
Gemfile.lock Normal file
View File

@@ -0,0 +1,79 @@
GEM
remote: https://rubygems.org/
specs:
addressable (2.8.1)
public_suffix (>= 2.0.2, < 6.0)
colorator (1.1.0)
concurrent-ruby (1.1.10)
em-websocket (0.5.3)
eventmachine (>= 0.12.9)
http_parser.rb (~> 0)
eventmachine (1.2.7)
ffi (1.15.5)
forwardable-extended (2.6.0)
http_parser.rb (0.8.0)
i18n (1.12.0)
concurrent-ruby (~> 1.0)
jekyll (4.3.0)
addressable (~> 2.4)
colorator (~> 1.0)
em-websocket (~> 0.5)
i18n (~> 1.0)
jekyll-sass-converter (>= 2.0, < 4.0)
jekyll-watch (~> 2.0)
kramdown (~> 2.3, >= 2.3.1)
kramdown-parser-gfm (~> 1.0)
liquid (~> 4.0)
mercenary (>= 0.3.6, < 0.5)
pathutil (~> 0.9)
rouge (>= 3.0, < 5.0)
safe_yaml (~> 1.0)
terminal-table (>= 1.8, < 4.0)
webrick (~> 1.7)
jekyll-sass-converter (2.2.0)
sassc (> 2.0.1, < 3.0)
jekyll-seo-tag (2.8.0)
jekyll (>= 3.8, < 5.0)
jekyll-watch (2.2.1)
listen (~> 3.0)
just-the-docs (0.5.0)
jekyll (>= 3.8.5)
jekyll-seo-tag (>= 2.0)
rake (>= 12.3.1)
kramdown (2.4.0)
rexml
kramdown-parser-gfm (1.1.0)
kramdown (~> 2.0)
liquid (4.0.3)
listen (3.7.1)
rb-fsevent (~> 0.10, >= 0.10.3)
rb-inotify (~> 0.9, >= 0.9.10)
mercenary (0.4.0)
pathutil (0.16.2)
forwardable-extended (~> 2.6)
public_suffix (5.0.0)
rake (13.0.6)
rb-fsevent (0.11.2)
rb-inotify (0.10.1)
ffi (~> 1.0)
rexml (3.2.5)
rouge (4.0.0)
safe_yaml (1.0.5)
sassc (2.4.0)
ffi (~> 1.9)
terminal-table (3.0.2)
unicode-display_width (>= 1.1.1, < 3)
unicode-display_width (2.3.0)
webrick (1.7.0)
PLATFORMS
arm64-darwin-21
x86_64-darwin-19
x86_64-linux
DEPENDENCIES
jekyll (~> 4.3)
just-the-docs (= 0.5.0)
BUNDLED WITH
2.3.9

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2022 just-the-docs
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

173
README.md
View File

@@ -1,2 +1,171 @@
# endorphin # just-the-docs-template
The Ender 5 as it should be
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 `Gemfile` and loads the `just-the-docs` gem;
- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages.
To get started with creating a site, just click "[use this template]"!
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).
After completing the creation of your new site on GitHub, update it as needed:
## Replace the content of the template pages
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)
## Changing the version of the theme and/or Jekyll
Simply edit the relevant line(s) in the `Gemfile`.
## Adding a plugin
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`:
```ruby
gem "jekyll-default-layout"
```
- And add the following to your site's `_config.yml`:
```yaml
plugins:
- jekyll-default-layout
```
Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
## Publishing your site on GitHub Pages
1. If your created site is `YOUR-USERNAME/YOUR-SITE-NAME`, update `_config.yml` to:
```yaml
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
```
2. Push your updated `_config.yml` to your site on GitHub.
3. In your newly created repo on GitHub:
- go to the `Settings` tab -> `Pages` -> `Build and deployment`, then select `Source`: `GitHub Actions`.
- if there were any failed Actions, go to the `Actions` tab and click on `Re-run jobs`.
## Building and previewing your site locally
Assuming [Jekyll] and [Bundler] are installed on your computer:
1. Change your working directory to the root directory of your site.
2. Run `bundle install`.
3. Run `bundle exec jekyll serve` to build your site and preview it at `localhost:4000`.
The built site is stored in the directory `_site`.
## Publishing your built site on a different platform
Just upload all the files in the directory `_site`.
## Customization
You're free to customize sites that you create with this template, however you like!
[Browse our documentation][Just the Docs] to learn more about how to use this theme.
## Hosting your docs from an existing project repo
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.
### Copy the template files
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.
2. Create a `docs` directory at your project root and copy all remaining template files into this directory.
### Modify the Github Actions worklow
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.
1. Set the default `working-directory` param for the build job.
```yaml
build:
runs-on: ubuntu-latest
defaults:
run:
working-directory: docs
```
2. Set the `working-directory` param for the Setup Ruby step.
```yaml
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.1'
bundler-cache: true
cache-version: 0
working-directory: '${{ github.workspace }}/docs'
```
3. Set the path param for the Upload artifact step:
```yaml
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: "docs/_site/"
```
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.
```yaml
on:
push:
branches:
- "main"
paths:
- "docs/**"
```
## Licensing and Attribution
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].
----
[^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).
[Jekyll]: https://jekyllrb.com
[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
[GitHub Pages]: https://docs.github.com/en/pages
[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
[Bundler]: https://bundler.io
[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate
[`jekyll-default-layout`]: https://github.com/benbalter/jekyll-default-layout
[`jekyll-seo-tag`]: https://jekyll.github.io/jekyll-seo-tag
[MIT License]: https://en.wikipedia.org/wiki/MIT_License
[starter workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml
[actions/starter-workflows]: https://github.com/actions/starter-workflows/blob/main/LICENSE

8
_config.yml Normal file
View File

@@ -0,0 +1,8 @@
title: Just the Docs Template
description: A starter template for a Jeykll site using the Just the Docs theme!
theme: just-the-docs
url: https://just-the-docs.github.io
aux_links:
Template Repository: https://github.com/just-the-docs/just-the-docs-template

32
index.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: Home
layout: home
---
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.
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.
More specifically, the created site:
- uses a gem-based approach, i.e. uses a `Gemfile` and loads the `just-the-docs` gem
- uses the [GitHub Pages / Actions workflow] to build and publish the site on GitHub Pages
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.
[Browse our documentation][Just the Docs] to learn more about how to use this theme.
To get started with creating a site, just click "[use this template]"!
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.
----
[^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).
[Just the Docs]: https://just-the-docs.github.io/just-the-docs/
[GitHub Pages]: https://docs.github.com/en/pages
[README]: https://github.com/just-the-docs/just-the-docs-template/blob/main/README.md
[Jekyll]: https://jekyllrb.com
[GitHub Pages / Actions workflow]: https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/
[use this template]: https://github.com/just-the-docs/just-the-docs-template/generate