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, not 3.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

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 the Contribution category.
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
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”.

Lists

Unordered list

* Item 1
    * Item 2
* Item 3

Item 1
- Item 2
Item 3

Ordered list

Item 1
Item 2
Item 3
    * Item 4

Item 1
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." %}

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.

Sample gallery.

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.

Round LibrePhotos logo

Excerpt 2.

Button

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.

Overview

Previewing Locally

Manually

Using Dev Container

Naming

Categories

File Names

Front Matter

Templated Elements

Text Formatting

Bold

Italics

Underline

Strikethrough

Monospace

Superscript

Subscript

Links

Inline code block

Formatted code block

Abbreviation

Lists

Unordered list

Ordered list

Notices

Buttons

Blockquotes

Single line blockquote

Multi line blockquote with cite reference

Tables

Term/Definition Lists

Images & Videos

Figures (Images)

Videos

YouTube

Vimeo

Google Drive

Stored in this Repository

Gallery

Feature Row

Square LibrePhotos logo

Round LibrePhotos logo

Square LibrePhotos logo