Skip to content

Commit b8197ae

Browse files
PhilReedDataPhilReedData
authored
Follow-on PR26, guidance on relative URLs
Add to contribution guide how to use relative URLs for images and links. Note that pages can be served from directory.
1 parent 723fb15 commit b8197ae

File tree

1 file changed

+82
-2
lines changed

1 file changed

+82
-2
lines changed

‎tech/contributing-to-pages.md

Lines changed: 82 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,48 @@ redirect_from: /contributing-to-pages
66

77
If you find a mistake or wish to make an improvement to these pages, you can do so. For a small mistake, just let us know by [contacting us](contacting-us). For other changes you can also access and edit the pages themself.
88

9+
{% include callout.html type="important" content="
10+
Note that FAIRDOM-SEEK instances are highly customisable.
11+
This set of documentation pages can be customised for your local instance.
12+
For example, they can be served at the root level or from within a directory.
13+
Please contact your local instance admin for more information.
14+
" %}
15+
16+
## Editing and adding pages
17+
18+
These pages can be found in GitHub at [https://github.com/seek4science/seek-documentation](https://github.com/seek4science/seek-documentation). Pages are in [Markdown](https://help.github.com/articles/markdown-basics/) format, with a _.md_ extension, but get converted into HTML for you.
19+
New pages require a formatter at the top, that looks like:
20+
```yaml
21+
---
22+
title: my lovely page
23+
---
24+
```
25+
26+
For example, this page can be found at [https://raw.githubusercontent.com/seek4science/seek-documentation/main/tech/contributing-to-pages.md](https://raw.githubusercontent.com/seek4science/seek-documentation/main/tech/contributing-to-pages.md).
27+
28+
The **home, about, user guide, and technical references pages** use a remote theme called [ELIXIR Toolkit Theme](https://elixir-belgium.github.io/elixir-toolkit-theme/) (ETT). The ETT theme provides additional support for styling and navigation, including the sidebar menus. The _title_ metadata is used to create a first-level heading at the top of the page. Do not include it again. Instead, use `##` and `###` for subheadings (second- and third-level, respectively).
29+
30+
The site can be served from a root domain/sub-domain (for example, `docs.site.com`) or from a directory (for example, `site.com/docs`). To support sites that are served from a directory, all links to pages within the site must be given as relative paths, not absolute paths. We use a [Jekyll filter](https://jekyllrb.com/docs/liquid/filters/) to achieve this, for example:
31+
```
32+
{% raw %}Please visit our [Contributors guide]({{ "/tech/contributing" | relative_url }}).{% endraw %}
33+
```---
34+
title: Contributing to these pages
35+
redirect_from: /contributing-to-pages
36+
---
37+
38+
39+
If you find a mistake or wish to make an improvement to these pages, you can do so. For a small mistake, just let us know by [contacting us](contacting-us). For other changes you can also access and edit the pages themself.
40+
41+
{% include callout.html type="important" content="
42+
Note that FAIRDOM-SEEK instances are highly customisable.
43+
This set of documentation pages can be customised for your local instance.
44+
For example, they can be served at the root level or from within a directory.
45+
Please contact your local instance admin for more information.
46+
" %}
47+
948
## Editing and adding pages
1049
11-
These pages can be found in Github at [https://github.com/seek4science/seek-documentation](https://github.com/seek4science/seek-documentation). Pages are in [Markdown](https://help.github.com/articles/markdown-basics/) format, with a _.md_ extension, but get converted into HTML for you.
50+
These pages can be found in GitHub at [https://github.com/seek4science/seek-documentation](https://github.com/seek4science/seek-documentation). Pages are in [Markdown](https://help.github.com/articles/markdown-basics/) format, with a _.md_ extension, but get converted into HTML for you.
1251
New pages require a formatter at the top, that looks like:
1352
```yaml
1453
---
@@ -18,7 +57,48 @@ title: my lovely page
1857

1958
For example, this page can be found at [https://raw.githubusercontent.com/seek4science/seek-documentation/main/tech/contributing-to-pages.md](https://raw.githubusercontent.com/seek4science/seek-documentation/main/tech/contributing-to-pages.md).
2059

21-
The **top level, technical reference, user guide pages** use a remote theme called [ELIXIR Toolkit Theme](https://elixir-belgium.github.io/elixir-toolkit-theme/) (ETT). The ETT theme provides additional support for styling and navigation, including the sidebar menus. The _title_ metadata is used to create a first-level heading at the top of the page. Do not include it again. Instead, use `##` and `###` for subheadings (second- and third-level, respectively).
60+
The **home, about, user guide, and technical references pages** use a remote theme called [ELIXIR Toolkit Theme](https://elixir-belgium.github.io/elixir-toolkit-theme/) (ETT). The ETT theme provides additional support for styling and navigation, including the sidebar menus. The _title_ metadata is used to create a first-level heading at the top of the page. Do not include it again. Instead, use `##` and `###` for subheadings (second- and third-level, respectively).
61+
62+
The site can be served from a root domain/sub-domain (for example, `docs.site.com`) or from a directory (for example, `site.com/docs`). To support sites that are served from a directory, all links to pages within the site must be given as relative paths, not absolute paths. We use a [Jekyll filter](https://jekyllrb.com/docs/liquid/filters/) to achieve this, for example:
63+
```
64+
{% raw %}Please visit our [Contributors guide]({{ "/tech/contributing" | relative_url }}).{% endraw %}
65+
```
66+
67+
All links to images within the site must also be given as relative paths (with alt description), for example:
68+
```
69+
{% raw %}![Registration 1]({{ "/images/user-guide/register_1.png" | relative_url }}){:.screenshot}{% endraw %}
70+
```
71+
72+
To add your new page to the sidebar, add a line to the data file:
73+
`_data` ► `sidebars` ► `userguide.yml`, `tech.yml` or `about.yml`.
74+
More details are available from the [ETT theme documentation](https://elixir-belgium.github.io/elixir-toolkit-theme/navigation_structures).
75+
76+
The **about pages** (top level) require additional lines at the top to display correctly:
77+
```yaml
78+
---
79+
sidebar: about
80+
---
81+
```
82+
## Viewing your changes locally
83+
84+
If you want to view your changes as you edit them, with Ruby installed you can install and run Jekyll with:
85+
86+
```sh
87+
gem install bundler
88+
bundle install
89+
bundle exec jekyll serve
90+
```
91+
and then goto [localhost:4000](http://localhost:4000). For more information please see [Using Jekyll with Pages](https://help.github.com/articles/using-jekyll-with-pages/).
92+
93+
## Committing your changes
94+
95+
You can make a change by forking and issuing a pull request. If contributing through GitHub is unfamiliar to you, please read [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/).
96+
97+
98+
All links to images within the site must also be given as relative paths (with alt description), for example:
99+
```
100+
{% raw %}![Registration 1]({{ "/images/user-guide/register_1.png" | relative_url }}){:.screenshot}{% endraw %}
101+
```
22102

23103
To add your new page to the sidebar, add a line to the data file:
24104
`_data` ► `sidebars` ► `userguide.yml`, `tech.yml` or `about.yml`.

0 commit comments

Comments
 (0)