The [Just the Docs Template] provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "[use the template]"!
A simple and customisable theme for building your GitLab pages site.
Note: To use the theme, you do ***not*** need to clone or fork the [Just the Docs repo]! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs.
## Usage
You can easily set the site created by the template to be published on [GitHub Pages] – the [template README] file explains how to do that, along with other details.
### 1. Fork this project
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.[^2] And you will be able to deploy your local build to a different platform than GitHub Pages.
Fork this project by clicking the __*Fork*__ button at the top right corner of this page. Forking means that you now copied this entire project and all the files into your account.
More specifically, the created site:
### 2. Rename the project
- 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
In your version of the project, click on __*Settings*__ on the left (the cog icon) and rename the project (*Project name*) to something meaningful to you.
Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins.
In the __*Advanced*__ settings (bottom of the page), check that the path matches what you expect given your desired project name.
### Use RubyGems
### 3. Set the _config.yml url and update the "served at " description
Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
In the file `_config.yml`, update line 18 so the baseurl matches the path of your project. The baseurl should start with `"/pages/"` and end without a trailing `/`.
Add this line to your Jekyll site's `Gemfile`:
In the project settings, update the description to match the address of where your build page will be rendered. This is the combined url+baseurl addresses from your `_config.yml`.
```ruby
gem"just-the-docs"
```
### 4. Turn on CI Runners
And add this line to your Jekyll site's `_config.yml`:
You need to enable a "runner" in order for GitLab to "build"/"serve" your page. Go to __*Settings*__ > __*CI/CD*__ > __*Runners*__. Tick `enable shared runners`.
```yaml
theme:just-the-docs
```
### 5. Customize your website settings
And then execute:
Edit the `_config.yml` file to change any additional settings you want. To edit the file, click on it to view the file and then click on the pencil icon to edit it. The settings in the file are self-explanatory and there are comments inside the file to help you understand what each setting does. Any line that begins with a hashtag (`#`) is a comment, and the other lines are actual settings.
$ bundle
**We suggest you start by making a small change (for example updating the title or author) then commit this change. Making the commit will trigger the CI, which will take a few moments to build your page.** You can monitor the progress of the CI in `CI/CD pipleines` (rocket icon on the left navigation bar).
Or install it yourself as:
### 6. Add your own content
$ gem install just-the-docs
To add pages to your site, you can either write a markdown file (`.md`) or you can write an HTML file. It's much easier to write markdown than HTML, so that's the recommended approach ([here's a great tutorial](https://markdowntutorial.com/) if you need to learn markdown in 5 minutes).
Alternatively, you can run it inside Docker while developing your site
To see an example of a markdown file, click on any file that ends in `.md`, for example [`aboutme.md`](./aboutme.md). On that page you can see some nicely formatted text (there's a word in bold, a link, a few bullet points), and if you click on the pencil icon to edit the file, you'll see the markdown code that generated the pretty text. Very easy!
$ docker-compose up
## Customisation
## Usage
[View the documentation](https://pmarsceill.github.io/just-the-docs/) for additional usage usage information.
Take a look at the [Open WIN Community pages](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/) to see an example of a customised version of this theme. Don't forget to look at the GitLab repository for that site (follow the "[view on GitLab link](https://git.fmrib.ox.ac.uk/open-science/community/Open-WIN-Community)" to see how the customisation was achieved.
[View the documentation][Just the Docs] for usage information.
## Contributing
...
...
@@ -84,9 +79,9 @@ Bug reports, proposals of new features, and pull requests are welcome on GitHub
3. First class mobile experience
4. Make the content shine
## Development
## Testing and development
To set up your environment to develop this theme: fork this repo, the run `bundle install` from the root directory.
To set up your environment to test this theme locally (without pushing it to GitLab): fork this repo, the run `bundle install` from the root directory on your terminal.
A modern [devcontainer configuration](https://code.visualstudio.com/docs/remote/containers) for VSCode is included.
