Skip to content

Commit 8585827

Browse files
kenatcampbellmusclelabkenatcampbellmusclelab
committed
2 parents 4f08551 + 609009f commit 8585827

1 file changed

Lines changed: 2 additions & 175 deletions

File tree

‎docs/README.md‎

Lines changed: 2 additions & 175 deletions
Original file line numberDiff line numberDiff line change
@@ -1,176 +1,3 @@
1-
# just-the-docs-template
1+
A set of tools for statistics, data-wrangling, and creating publication-quality figures
22

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

0 commit comments

Comments
 (0)