Contributing Guide¶

Overview¶

This documentation site is written using Markdown, and uses Material for MkDocs, which is a Theme for MKDocs site generator tool.

The site is hosted on Github pages, and Github actions is used to automatically build the site from merges on the main branch from the markdown content.

To Contribute¶

Local Install of the Repository and Tools¶

These items must be done once.

Clone the github repository locally on your computer:

git clone https://github.com/exosite/docs_exosite.git

Install Material for MKDocs, which uses Python3. The following command will install mkdocs-material in addition to extra plugins being used.

pip install -r requirements.txt

Updating Frameworks / libraries¶

Recommend running this locally to check for updates often.

To update to the latest mkdocs-material and additional dependencies, run:

pip install -r requirements.txt --upgrade 

Building and Previewing Changes Locally¶

As you make updates to the content, you can (and should) build and run the site locally to verify your edits.

To build and serve your site locally run the following command from the repository directory:

mkdocs serve

You'll notice that at some point it will begin serving the site locally, with the message: Serving on http://127.0.0.1:8000 In your computer browser, go to that address: http://127.0.0.1:8000/

As edits are made, whenever a file is saved, it will update. It can take several seconds for the update to propagate to the hosted pages.

mkdocs build

Your shell will output information, errors, warnings, and 404's that may be the result of your edits which need to be resolved before committing to a PR.

Making Updates¶

Create a branch that will be used for your pull request. Typically this branch should be named for a Jira ticket and/or the changes being made.

Note that commits to main are not allowed in most cases.

Please create a Pull Request when you want to commit your changes on our branch to the main branch.

A Github Action is set up to automatically build all updates to the main branch in github. https://github.com/exosite/docs_exosite/tree/main/.github/workflows

Note: In the rare cased needed (emergency), to manually update Github pages, use:

mkdocs gh-deploy --force

Guidelines¶

All content is in the /docs directory in this repository other than the home page override (see /overrides). The structure inside of this main docs directory attempts to be around subject matter.

.
├─ docs/
│  └─ assets/   # current 'everything collection of images, try not to use
│     └─ stylesheets/ # Exosite theme tweaks
│  ├─ changelog/
│  ├─ device-connectivity/
│  ├─ exchange/
│  ├─ exoedge/
│  ├─ exosense/
...
├─ overides/ # home page html, custom icons
└─ mkdocs.yml # nav, plug-in settings, theme settings, etc

For a new page to show up in the navigation, it must be added to the /mkdocs.yml file, under the nav: key. (Follow the formating for all of the other pages and sections).

nav:
  - Home: index.md
  - Getting Started:
    - Sign-up and deploy ExoSense: getting-started/deploy.md
    ...

  - exclude-search:
      exclude:
          - page-i-do-not-want-in-search.md

.
└─ docs/
   └─ exoedge/
      ├─ assets/
      └─ article1.md

Links¶

Links are relative to the current file's directory.

As a reminder:

/ is the root directory (should not be used as it may not be the same when built and hosted on dev, staging, local instances )
./ is the current directory of the current file
../ is the parent directory of the current file

└─ docs/
  ├─ directory1/
  │  ├─ assets/
  │  ├─ article1.md
  │  └─ article1-1.md
  ├─ directory2/
  │   ├─ assets/
  │   └─ article2.md
  ├─ directory3/
  │  ├─ assets/
  │  └─ article3.md
  └─ article0.md      

[my link text](article1-1.md)

[my link text](article1-1.md#header1)

[my link text](../article0.md)

[my link text](../directory3/article3.md)

[my link text][id-1]

[id-1]: article1-1.md

[Exosite Support][exosupport]

[exosupport]: https://support.exosite.com

Formatting¶

Standard markdown formatting is used, which you can reference here: https://daringfireball.net/projects/markdown/.

MKDocs uses Python-Markdown to render the pages as HTML, if you are interested, you can read about the few exceptions here: Writing markdown with MKDocs.

Images¶

Standard markdown support for images, plus the additional additional support from Material for MKDocs for images.

You can change the image width with { width="300" } class

![](assets/exosense/asset_files.png){: .screenshot }{ width="300" }

Screenshot Recommendations¶

To get a standard consistent shadowbox on screenshots that looks ok for both white/dark background, we've added a custom class to add a box-shadow that can be used inline with your markdown.

![](assets/exosense/asset_files.png){: .screenshot .image-ninety}

Result:

.screenshot {
  box-shadow: rgba(0, 0, 0, 0.4) 0px 0.25rem 0.5rem 0px;"
}

.image-fifty {
  width: 50%;
}

.image-ninety {
  width: 90%;
}

.image-seventyfive {
  width: 75%;
}

Dark/Light theme images¶

You can have two different images and only show one based on the dark / light mode using a hash at the end of the image link.

https://squidfunk.github.io/mkdocs-material/reference/images/#light-and-dark-mode

![Image title](assets/exosense/asset_files.png#only-light)
![Image title](assets/exosense/asset_files-dark.png#only-dark)

More image options¶

<figure>
  <img src="../assets/exosense/asset_files.png" style="box-shadow: rgba(0, 0, 0, 0.4) 0px 0.25rem 0.5rem 0px;"/>
  <figcaption>Asset Content</figcaption>
</figure>

Call-outs / Admonitions¶

Hints, warnings, info call-outs can be created using this format:

!!! note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Which will look like this:

More info can be found at Material for MKDocs admonitions.

You can also use a custom Exosite admonition using format:

!!! exosite "Your Subject Here"
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Code Blocks¶

Standard markdown support for code blocks, plus Material for MKDocs additional code block handling

Example of syntax:

``` JSON
{ "key":"value1","key2":3}
```

{ "key":"value1","key2":3}

Extra Exosite icons¶

Additional icons can be added. These are found in /overides/.icons/exosite.

You can use them inline by using the format :exosite-device-1:, which generates ->