Hestia Guide

This repository contains the raw content of the guide written in Markdown language.

Every file under src/content will be automatically deployed to https://www-dev.hestia.earth/guide?branc= for testing.

Note: only lower chars, dashes (-) and numbers are allowed in the filenames.

Writing Guidelines

1. Create a new file under src/content and make sure the filename only uses lowercase letters, numbers and dashes.
2. Add the file to the src/index.yaml file, defining the structure of the menu.
3. Start the file with a header level 1 using #. Example:

   # This is the header
   
   This is the content.
   
   ## This is a sub-header

The header level 1 will be automatically used as Title for the Guide page, so please try to keep it short, and do not use special characters.

The second line (omitting the blank lines) will be used as abstract.

Example: if you are adding a page called "Signing in" under "HESTIA 101":

• add src/content/hestia-101/signin.md file;
• add a new entry - id: signin under the pages array for hestia-101 in src/index.yaml file.

This will automatically:

• show the page under "HESTIA 101" menu
• show the page as item number N in the menu (depending on the page index in the yaml file)
• match the page with the url hestia-101-signin
• the title of the page will be used also in the menu

Adding metadata

It is possible to add a list of metadata, using the following format:

/<name of metadata> ~Title~

These metadata must be added at the end of the file, one per line. The list of metadata is:

| Name | Can be added multiple times | Description | | ---- | ---- | ---- | | author | ✅ | Name of the person that wrote the file | | contributor | ✅ | Name of the person that contributed to write the file | | tag | ✅ | Used to group pages together as "related" |

Example:

# This is the title

This is the content of the page.

/author ~John Doe~
/tag ~Hestia~
/tag ~Beginners~

Linking pages together

To link pages together via the "Related Topics" section on a page, you can add /tag ~tag name~ on the pages you want to link together. Example:

• add /tag ~soc modelling~ on page 1
• add /tag ~soc modelling~ on page 2
• add /tag ~soc modelling~ on page 3

On page 1, page 2 and 3 will appear under "Related Topics". Similarly, on page 2, page 1 and 3 will appear under "Related Topics".

Adding links to other pages

Links to other pages, on the website, or to external websites, can be added with standard markdown syntax:

[link title](https://some-website.com/link)
[link title](https://hestia.earth/guide/other-page)
# this also works as long as it is a page on the website
[link title](/guide/other-page)
[link title](/schema/Cycle)

Adding a table

Normally, to add a table, you just need to use the default markdown table style:

| Header | Header | | - | - | | cell1 | cell2 |

However in some cases, you might need finer control over the structure (like merging multiple cells with colspan attribute). In that case, tables need to be wrapped manullay using:

<div class="table-container is-responsive">
  <table class="table is-fullwidth is-hoverable is-striped">
    <!-- Insert content here -->
  </table>
</div>

Note: to add multiple tables one after another, insert only 1 empty line between the 2 tables:

| Header | Header |
| - | - |
| cell1 | cell2 |

| Header | Header |
| - | - |
| cell1 | cell2 |

If you insert 2 lines, the display may brake.

Adding collapsible groups

Collapsible blocks (hides the content with a toggle icon) can be added using html code as following:

<div class="collapsibles">
  <div class="collapsible-group">
    <div class="collapsible-header">
      <span>First collapsible header</span>
    </div>
    <div class="collapsible-content">First collapsible content</div>
  </div>

  <div class="collapsible-group">
    <div class="collapsible-header">
      <span>Second collapsible header</span>
    </div>
    <div class="collapsible-content">Second collapsible content</div>
  </div>
</div>

Adding a video or an image

1. Copy your image in the guide-assets folder
2. Reference your image in the markdown:

![Image title](/assets/my-image.png)