Contributing to Docs

Thank you for your interest in contributing to the Fermyon documentation. Below are a few pointers designed to help you contribute.

Technical Documentation Types

The following points will help guide your contribution from a resource-type perspective; essentially we would really appreciate you creating and contributing any of the following 4 resource types.

1. Tutorials

Tutorials are oriented toward learning. Tutorials are designed to get a user started on something new (that they have not tried before). You can think of a tutorial as a lesson i.e. teaching a Spin user how to use Redis to persist data. The tutorial may contain many logically ordered steps i.e. installing Spin, installing Redis, using Spin templates, configuring a Spin application and so forth. The desired outcome for a tutorial is for the user to have a working deployment or application. Think of it as a lesson in how to bake a cake.

2. How-To Guides

How-to guides are oriented towards showing a user how to solve a problem, which leads them to be able to achieve their own goal. The how-to guide will follow a series of logical steps. Think of it as providing a recipe for the user’s creativity. For example, you can show a user how to develop a Spin application without telling them what the application must do; that is up to the user’s imagination.

3. Reference

Reference resources are merely a dry description; describing the feature in its simplest form. A great example of a reference resource is the Spin CLI Reference page. You will notice that the CLI Reference page simply lists all of the commands and available options.

4. Explanation

An explanation resource is written using a deep-dive approach i.e. providing a deep explanation with the view to impart a deep understanding of a particular concept, feature or product. You may find your contribution is so in-depth that it becomes a long form article like a blog post. If that is the case, please get in touch and we can discuss options around getting your content published on another platform; like the Fermyon Blog.

Tying It All Together

You will notice that the menu system is organized in terms of “Tutorial”, “How-To”, “Reference” and so forth. When you write your contribution please decide which product (Cloud, Spin, Bartholomew) category it falls into and also which resource type it aligns with. Armed with that information you can go ahead and create your new file. For example, your “how-to” resource on “developing a Spin application” in Fermyon cloud would be saved to the content/cloud/ folder; specifically, content/cloud/ and the menu item (for the left-hand-side menu) would be added to the templates/cloud_sidebar.hbs file, as shown below.

cloud develop example

The resulting output would be as follows.

cloud develop example

Documents Relevant to Two or More Projects

If a document is relevant to two or more projects it is advised to place it in the new common folder area (i.e. as opposed to just placing it in the spin folder or just placing it in cloud folder). Items in the common area can still be linked to from any of the menu templates i.e. spin_main, cloud_main and common_main .hbs templates all link to this how-to-contribute document; which you are currently reading.

Technical Documentation Procedure (Video - Brief Explanation)

Technical Documentation Procedure (Text - Detailed Explanation)

1. Fork the Repository

The first step is to fork the developer repository, from Fermyon’s GitHub, to your own GitHub account.

Fork the repository

Ensure that you are forking the developer repository to your own GitHub account; where you have full editing privileges.

2. Clone the Fork

Copy the URL from the UI in readiness for running the git clone command.

Fork the repository

Go ahead and clone the new fork that you just created (the one which resides in your own GitHub account):

$ cd ~
$ git clone
$ cd developer

3. Create New Branch

Create a new branch that will house all of your changes for this specific contribution:

$ git checkout -b my_new_branch

4. Add Upstream

Create a new remote for the upstream (a pointer to the original repository to which you are contributing):

$ git remote add upstream

5. Code Blocks, Annotations and Table of Contents (ToC)

It is highly recommended that you use either the <!-- @selectiveCpy --> or the <!-- @nocpy --> annotation before each of your code blocks, and that each code block defines the appropriate syntax highlighting. The annotation can be skipped for code blocks with example code snippets i.e. non-terminal or generic output examples.

The selective copy annotation (<!-- @selectiveCpy -->) is intended for use when communicating code and/or CLI commands for the reader to copy and paste. The selective copy annotation allows the reader to see the entire code block (both commands and results) but only copies the lines that start with $ into the reader’s clipboard (minus the $) when the user clicks the copy button. For example, copying the following code block will only copy echo "hello" into your clipboard, for pasting.

$ echo "hello"

Note: If the command, that starts with $, is deliberately spread over two lines (by escaping the newline character), then the copy mechanism will still copy the second line which is technically still part of that single command.

The no copy annotation (<!-- @nocpy -->) precedes a code block where no copy and pasting of code is intended. If using the no copy attribute please still be sure to add the appropriate syntax highlighting to your code block (for display purposes). For example:

<!-- @nocpy -->

Some generic code not intended for copying/pasting

Multi-tab code blocks have recently been implemented. Examples can be seen in the Spin installer documentation]( and Spin Key/Value documentation. The above examples demonstrate how tabs can either represent platforms i.e. Windows, Linux and macOS or represent specific programming languages i.e. Rust, JavaScript and Golang etc. Here is a brief example of how to implement multi-tab code blocks when writing technical documentation for this site, using markdown.

The first step to implementing multi-tab code blocks is placing the enable_shortcodes = true configuration at the start of the .md file. Specifically, in the .md file’s frontmatter.

The markup to create tabs in markdown is as follows

{{ tabs "Os" }}

{{ startTab "Windows"}}

To list files on windows use `dir`

<!-- @selectiveCpy -->

$ dir hello_fermyon
and script in windows have the extension `.bat`

<!-- @nocpy -->


{{ blockEnd }}

{{ startTab "Linux"}}

To list files on linux use `ls`

<!-- @selectiveCpy -->

$ ls

and script in linux have the extension `.sh`

<!-- @nocpy -->


{{ blockEnd }}
{{ blockEnd }}

The next section covers the highly recommended use of ToCs.

Implementing a Table of Contents (ToC)

If you create content with many headings it is highly recommended to place a ToC in your markdown file. There are excellent extensions (such as this Visual Studio Code Extension called markdown-all-in-one which will automatically generate your ToC).

6.1 Checking Your Content - Using NPM

Once you are satisfied with your contribution, you can programmatically check your content.

If you have not done so already, please go ahead and perform the npm install command; to enable Node dependencies such as markdownlint-cli2. Simply run the following command, from the root of the developer repository:

$ npm install

With all Node dependencies installed, you can now check for broken links (which takes several minutes) and also lint your markdown files. Simply run the following command, from the root of the developer repository:

$ npm run test

Hint: Optionally you can run only the linter with the following command:

# Example of how to lint all Markdown files in a local folder (in this case the spin folder) 
npx markdownlint-cli2 content/spin/*.md \"#node_modules\"
# Example of how to lint a local Markdown file
npx markdownlint-cli2 content/spin/ \"#node_modules\"

Note: Whilst the npm run test command (which lints and also programmatically checks all URLs) does take extra time to complete it must be utilized before you push changes; preventing the potential pushing of broken URLs to the developer documentation site.

6.2 Generating Indexing For Your Content

The documentation site implements in-house search and therefore it is recommended to generate a new index each time you update and push changes to the developer documentation repository. This is done simply by using the following command; in the developer directory:

$ npm run build-index

6.3 How To Properly Edit CSS Styles

The following section (the running of the npm run styles command) is not necessary unless you are editing styles i.e. updating .scss files, in order to generate new .css files, as part of your contribution.

Directly editing .css files is not recommended, because .css files are overwritten. Instead, if you would like to make and test a new/different style please go ahead and update the appropriate .scss file. The following command will automatically update the .css file that is relevant to the .scss file that you are editing:

$ npm run styles

The above command is designed to be run in the background; enabling you to view your design changes (that are reflected in the .css) while you are editing the .scss in real-time. If you are not running this command in the background (i.e. just deliberately regenerating the .css files once), then the above command can be stopped by pressing Ctrl + C.

6.4 Checking Your Content - Using Bartholomew’s CLI

The Bartholomew Command Line Interface (CLI) Tool is called bart. The bart CLI is a tool that simplifies working with Bartholomew projects (by now you probably already know that Bartholomew is our in-house WebAssembly (Wasm) content management system (CMS) that powers our official Website). And this (our official documentation) site. The bart CLI is handy to ensure quality assurance of new and existing content. Installing the CLI is a cinch, so please go ahead and use it when contributing.

To build the Bartholomew CLI from source perform the following commands:

$ cd ~
$ git clone
$ cd ~/bartholomew
$ make bart

Once built, you will find the bart CLI executable in the ~/bartholomew/target/release directory. However, for convenience it would be a great idea to go ahead and add the bart executable to your system path, for example:

$ sudo mv ~/bartholomew/target/release/bart /usr/local/bin/

Once installed, you can use the CLI’s --help flag to learn more. For example:

$ bart --help
bart 0.6.0
The Bartholomew CLI

    bart <SUBCOMMAND>

    -h, --help       Prints help information
    -V, --version    Prints version information

    calendar    Print the content calendar for a Bartholomew website
    check       Check content and identify errors or warnings
    help        Prints this message or the help of the given subcommand(s)
    new         Create a new page or website from a template

Let’s take a quick look at how you can use the bart CLI to check any content that you are wanting to contribute.

7. Checking Web Pages

The bart CLI can be used to check content by simply passing in the content as a parameter; as shown below:

$ bart check content/
✅ content/

8. Add Changes

Once your changes have been checked, go ahead and add your changes by moving to a top-level directory, under which your changes exist i.e. cd ~/developer.

Add your changes by running the following command, from the root of the developer repository:

$ git add

9. Commit Changes

Before committing, please ensure that your GitHub installation is configured sufficiently so that you can --signoff as part of the git commit command. For example, please ensure that the and are configured in your terminal. You can check if these are set by typing git config --list.

If you need to set these values please use the following commands:

$ git config "yourusername"
$ git config ""

More information can be found at this GitHub documentation page called signing commits.

Type the following commit command to ensure that you sign off (–signoff), sign the data (-S) - recommended, and also leave a short message (-m):

$ git commit -S --signoff -m "Updating documentation"

Note: the --signoff option will only add a Signed-off-by trailer by the committer at the end of the commit log message. In addition to this, it is recommended that you use the -S option which will GPG-sign your commits. For more information about using GPG in GitHub see this GitHub documentation.

10. Push Changes

At this stage, it is a good idea to just quickly check what GitHub thinks the origin is. For example, if we type git remote -v we can see that the origin is our repo; which we a) forked the original repo into and b) which we then cloned to our local disk so that we could edit:

$ git remote -v

The above command will return output similar to the following:

origin (fetch)
origin (push)
upstream (fetch)
upstream (push)

Once you are satisfied go ahead and push your changes:

$ git push -u origin my_new_branch

11. Create a Pull Request

If you return to your GitHub repository in your browser, you will notice that a PR has automatically been generated for you.

Clicking on the green “Compare and pull request” button will allow you to add a title and description as part of the PR.

Compare and pull request

You can also add any information in the textbox provided below the title. For example, screen captures and/or code/console/terminal snippets of your contribution working correctly and/or tests passing etc.

Once you have finished creating your PR, please keep an eye on the PR; answering any questions as part of the collaboration process.

Thank You

Thanks for contributing.

Did we miss something?

Let us know how we can improve this project