Commit cd15afb8 authored by Cassandra Gould van Praag's avatar Cassandra Gould van Praag
Browse files

Update README.md for GitLab usage instructions.

parent f1f64538
Pipeline #11540 passed with stages
in 1 minute and 49 seconds
......@@ -11,39 +11,45 @@
![jtd](https://user-images.githubusercontent.com/896475/47384541-89053c80-d6d5-11e8-98dc-dba16e192de9.gif)
# Cass just-the-docs theme
# just-the-docs - WIN GitLab Pages theme
test.
A simple and customisable theme for buiding your GitLab pages site.
## Installation
## Usage
Add this line to your Jekyll site's Gemfile:
### 1. Fork this project
```ruby
gem "just-the-docs"
```
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.
And add this line to your Jekyll site's `_config.yml`:
### 2. Rename the project
```yaml
theme: just-the-docs
```
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. In the __*Advanced*__ settings (bottom of the page), check that the path matches what you expect given your desired project name.
And then execute:
### 3. Set the _config.yml url and update the "served at " description
$ bundle
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 `/`.
Or install it yourself as:
In the project settings, update the description to match the address of where your build page will be rendered. This is the combnined url+baseurl addresses from your `_config.yml`.
$ gem install just-the-docs
### 4. Turn on CI Runners
Alternatively, you can run it inside Docker while developing your site
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`.
$ docker-compose up
### 5. Customize your website settings
## Usage
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.
**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).
### 6. Add your own content
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).
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!
[View the documentation](https://pmarsceill.github.io/just-the-docs/) for additional usage usage information.
[View the documentation](https://pmarsceill.github.io/just-the-docs/) for 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 acheived.
## Contributing
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment