š Documentation
Overview
Contributing to our documentation is as simple as submitting a pull request to the librephotos.docs repository. Below is an explanation of all the templated elements available, and the naming conventions used, along with details of how to preview this site locally.
Previewing Locally
Manually
To compile the site and view it locally before submitting your pull request, first install the required packages for your OS:
- Ubuntu
- Windows (make sure you install Ruby
2.x
, not3.x
) - macOS
- Other Linux
Then open the terminal (Command Prompt on Windows) and navigate to the repository:
cd /path/to/folder
Install jekyll
and bundler
:
gem install jekyll bundler
Finally, to preview the site:
bundle exec jekyll serve
Some information will then be displayed - e.g.:
Configuration file: ~/librephotos-docs/_config.yml
Source: ~/librephotos-docs
Destination: ~/librephotos-docs/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 10.451 seconds.
Auto-regeneration: enabled for '~/librephotos-docs'
Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.
Visit the URL next to Server address:
.
Using Dev Container
For a simpler setup procedure, you can run the dev container in Visual Studio Code. To do this, open the folder you
cloned the librephotos.docs
repository to and run code .
. Visual Studio Code will then prompt you to run in a
container. The container will take a while to build.
When in the container, you can use Visual Studio Codeās Tasks function to build and host the site locally, at http://localhost:4000/.
Naming
Categories
Articles are organised by categories; each articleās category has to be declared in both the file name, and the file content. This will be explained below. The available categories are:
Category Name | Category Number |
---|---|
š Installation | 1 |
š User Guide | 2 |
Frequently Asked Questions | 3 |
Data Collection | 4 |
šØ Contribution | 5 |
Dev Resources | 6 |
File Names
File names contain four parts; and an example valid file name would be 0000-03-01-documentation.md
.
- First group of numbers: always
0000
. - Second group of numbers: the category number (from above). It should always be two digits.
- The example above has
03
, which means the article is in theContribution
category.
- The example above has
- Third group of numbers: the article number. Starting at
01
, this sets the order in which the articles appear. It should always be two digits.- The example above has
01
, meaning it is the first article in the category
- The example above has
- Fourth section (text): a short name for the article. This must end in
.md
.
Front Matter
The start of each page includes header info (called front matter), which ensures that articles are built correctly. Extra options are required if using galleries or feature rows, but the minimum requirement is:
---
title: "Article Title"
excerpt: "A short description of what the article is about."
last_modified_at: 2020-01-18
category: 1
---
Ensure you use a category ID from the table above and update the last_modified_at
date.
Templated Elements
Text Formatting
Bold
**text**
Produces: text
Italics
_text_
Produces: text
Underline
**text**
Produces: text
Strikethrough
~~text~~
Produces: text
Monospace
<kbd>text</kbd>
Produces: text
Superscript
<sup>text</sup>
Produces: text
Subscript
<sub>text</sub>
Produces: text
Links
[DuckDuckGo](https://duckduckgo.com)
Produces: DuckDuckGo
Inline code block
`<div></div>`
Produces: <div></div>
Formatted code block
```html
<div></div>
```
Produces:
<div></div>
Abbreviation
CSS stands for "Cascading Style Sheets".
\*[CSS]: Cascading Style Sheets
Produces: CSS stands for āCascading Style Sheetsā.
*[CSS]: Cascading Style Sheets
Lists
Unordered list
- Item 1
- Item 2
- Item 3
- Item 1
- Item 2
- Item 3
Ordered list
1. Item 1
1. Item 2
2. Item 3
- Item 4
- Item 1
- Item 2
- Item 3
- Item 4
Notices
Notice Type | Class |
---|---|
Default | .notice |
Primary | .noticeāprimary |
Info | .noticeāinfo |
Warning | .noticeāwarning |
Success | .noticeāsuccess |
Danger | .noticeādanger |
**Watch out!** A notice...
{: .notice}
Watch out! A noticeā¦
**Watch out!** A notice...
{: .notice--primary}
Watch out! A noticeā¦
**Watch out!** A notice...
{: .notice--info}
Watch out! A noticeā¦
**Watch out!** A notice...
{: .notice--warning}
Watch out! A noticeā¦
**Watch out!** A notice...
{: .notice--success}
Watch out! A noticeā¦
**Watch out!** A notice...
{: .notice--danger}
Watch out! A noticeā¦
Buttons
Links can be made into buttons by applying the btn
class:
[Link](#){: .btn}
Other classes can be added to change the buttonās appearance, as seen below. Size and type classes can be combined
(e.g. [Text](#){: .btn .btn--primary .btn--large}
) or used on their own (e.g. [Text](#){: .btn .btn--large}
).
Button Type | Example | Class | Syntax |
---|---|---|---|
Default | Text | .btn | [Text](#){: .btn} |
Primary | Text | .btn .btnāprimary | [Text](#){: .btn .btn--primary} |
Info | Text | .btn .btnāinfo | [Text](#){: .btn .btn--info} |
Success | Text | .btn .btnāsuccess | [Text](#){: .btn .btn--success} |
Warning | Text | .btn .btnāwarning | [Text](#){: .btn .btn--warning} |
Danger | Text | .btn .btnādanger | [Text](#){: .btn .btn--danger} |
Inverse | Text | .btn .btnāinverse | [Text](#){: .btn .btn--inverse} |
Light Outline | Text | .btn .btnālight-outline | [Text](#){: .btn .btn--light-outline} |
Button Size | Example | Class | Syntax |
---|---|---|---|
Extra Large | Text | .btn | [Text](#){: .btn .btn--primary .btn--x-large} |
Large | Text | .btn .btnāprimary | [Text](#){: .btn .btn--primary .btn--large} |
Default | Text | .btn .btnāinfo | [Text](#){: .btn .btn--primary} |
Small | Text | .btn .btnāsuccess | [Text](#){: .btn .btn--primary .btn--small} |
Blockquotes
Single line blockquote
> Stay hungry. Stay foolish.
Stay hungry. Stay foolish.
Multi line blockquote with cite reference
> People think focus means saying yes to the thing you've got to focus on. But that's not what it means at all. It means saying no to the hundred other good ideas that there are. You have to pick carefully.
>
> I'm actually as proud of the things we haven't done as the things I have done. Innovation is saying no to 1,000 things.
<cite>Steve Jobs</cite> --- Apple Worldwide Developers' Conference, 1997
{: .small}
People think focus means saying yes to the thing youāve got to focus on. But thatās not what it means at all. It means saying no to the hundred other good ideas that there are. You have to pick carefully.
Iām actually as proud of the things we havenāt done as the things I have done. Innovation is saying no to 1,000 things.
Steve Jobs ā Apple Worldwide Developersā Conference, 1997
Tables
| Employee | Salary | |
| ---------------------------------- | ------ | ---------- |
| John Doe | $15K | Some text. |
| [Jane Doe](https://duckduckgo.com) | $100K | More text. |
Employee | Salary | Ā |
---|---|---|
John Doe | $15K | Some text. |
Jane Doe | $100K | More text. |
Colons can be added to the column separators to define alignment:
| Left Align | Center Align | Right Align |
| :---------------------------------------- | :----------: | ----------: |
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
| ----------------------------------------- |
| cell1 | cell2 | cell3 |
| cell4 | cell5 | cell6 |
| ========================================= |
| Footer 1 | Footer 2 | Footer 3 |
Left Align | Center Align | Right Align |
---|---|---|
cell1 | cell2 | cell3 |
cell4 | cell5 | cell6 |
cell1 | cell2 | cell3 |
cell4 | cell5 | cell6 |
Footer 1 | Footer 2 | Footer 3 |
Term/Definition Lists
Term 1
: Definition 1.
Term 1
: Definition 2.
- Term 1
- Definition 1.
- Term 1
- Definition 2.
Images & Videos
Figures (Images)
Parameter | Required | Description |
---|---|---|
image_path | Required | Full path to image - e.g. /assets/images/filename.jpg . Use absolute URLs (including https:// and the domain) for those hosted externally. |
alt | Optional | Alternate text for image (displays if image fails to load). |
caption | Optional | Figure caption text. Markdown is allowed (e.g. bold, italics, links). |
Images stored in this repository should be in the /assets/images/
folder.
Usage:
{% include figure image_path="/assets/images/logo-round.png" alt="LibrePhotos logo" caption="Image caption." %}

Videos
Videos can be embedded if they are stored on YouTube, Vimeo, Google Drive, or this repository.
{% include video id="id" provider="provider" %}
Parameter | Required | Description |
---|---|---|
id |
Required | ID of the video |
provider |
Required | Hosting provider of the video: youtube , vimeo , google-drive , or local |
YouTube
To embed https://www.youtube.com/watch?v=XsxDH4HcOWA
(or https://youtu.be/XsxDH4HcOWA
):
{% include video id="XsxDH4HcOWA" provider="youtube" %}
Vimeo
To embed https://vimeo.com/212731897
:
{% include video id="212731897" provider="vimeo" %}
Google Drive
To embed https://drive.google.com/file/d/1u41lIbMLbV53PvMbyYc9HzvBug5lNWaO/preview
:
{% include video id="1u41lIbMLbV53PvMbyYc9HzvBug5lNWaO" provider="google-drive" %}
Stored in this Repository
Videos stored in this repository must be stored in the /assets/videos/
directory. To embed a video at
/assets/videos/video.mp4
:
{% include video id="video.mp4" provider="local" %}
Gallery
Galleries are groups of images.


They use some additional front matter:
gallery:
- url: /assets/images/logo-round.png
image_path: /assets/images/logo-round.png
alt: "Round LibrePhotos logo"
title: "Round LibrePhotos logo"
- url: /assets/images/logo-square.png
image_path: /assets/images/logo-square.png
alt: "Square LibrePhotos logo"
title: "Square LibrePhotos logo"
Name | Required | Description |
---|---|---|
url | Optional | URL of image to link to, which is opened when the gallery image is clicked. |
image_path | Required | Full path to image eg: /assets/images/image.jpg . Use absolute URLs (including https:// and the domain) for those hosted externally. |
alt | Optional | Alternate text for image (displays if image fails to load). |
title | Optional | Title text for image. Will display as a caption when gallery image is clicked, if url option has been specified. |
Include the gallery with:
{% include gallery caption="Sample **gallery**." %}
This also has some parameters:
Parameter | Required | Description | Default |
---|---|---|---|
id | Optional | To add multiple galleries to a document, uniquely name them in the front matter (by replacing gallery: in the example above) and reference them in {% include gallery id="gallery_id" %} |
gallery |
layout | Optional | Layout type. 2 column: half , 3 column: third , single column: '' (blank) |
Determined by gallery size. Two items: half , three or more items: third . |
class | Optional | Use to add a class attribute to the surrounding <figure> element for additional styling needs. |
Ā |
caption | Optional | Gallery caption description. Markdown is allowed. | Ā |
Feature Row
Feature rows contain three content blocks with text and an image.
Square LibrePhotos logo
Excerpt 1.
Square LibrePhotos logo
Excerpt 3.
They use some additional front matter:
feature_row:
- image_path: /assets/images/logo-grey.png
alt: "Grey LibrePhotos logo"
title: "Grey LibrePhotos logo"
excerpt: "Excerpt 1."
- image_path: /assets/images/logo-round.png
alt: "Round LibrePhotos logo"
title: "Round LibrePhotos logo"
excerpt: "Excerpt 2."
url: "/"
btn_label: "Button"
btn_class: "btn--inverse"
- image_path: /assets/images/logo-square.png
alt: "Square LibrePhotos logo"
title: "Square LibrePhotos logo"
excerpt: "Excerpt 3."
Name | Required | Description | Default |
---|---|---|---|
image_path | Required | Full path to image - e.g. /assets/images/image.jpg . Use absolute URLs (including https:// and the domain) for those hosted externally. |
Ā |
image_caption | Optional | Caption for image. Markdown is allowed | Ā |
alt | Optional | Alternate text for image(displays if image fails to load). | Ā |
title | Optional | Content block title. | Ā |
excerpt | Optional | Content block excerpt text. Markdown is allowed. | Ā |
url | Optional | URL that the button should link to. | Ā |
btn_label | Optional | Button text label. | more_label in UI Text data file. |
btn_class | Optional | Button style. | btn |
Include the feature row with:
{% include feature_row %}
This also has some parameters:
Include Parameter | Required | Description | Default |
---|---|---|---|
id | Optional | To add multiple rows to a document, uniquely name them in the front matter (by replacing feature_row: in the example above) and reference in {% include feature_row id="row2" %} |
feature_row |
type | Optional | Alignment of the featured blocks in the row. Options include: left , center , or right aligned. |
Ā |