Documentation – Contributing

About: Git and GitHub

Mon, 01 Jan 0001 00:00:00 +0000

For collaboration purposes, it is best if you create a GitHub account and fork the repository to your own account. Once you do this, you will be able to push your changes to your GitHub repository for others to see and use, and you will be able to create pull requests (PRs) in the official EGI documentation repository based on branches in your fork.

If you are new to git and GitHub you are advised to start by the two following articles providing simple tutorials:

GitHub official documentation is available at docs.github.com.

Tip

The first-contributions is a repository allowing anyone to freely learn and test creating a real Pull Request to an existing GitHub repository.

Additional documentation about the main steps for working with GitHub is also available in this section.

The GitHub contribution flow

In order to be able to send code update to the repository you need to:

fork the repository to your GitHub account
clone the repository on your local computer
create a feature branch where you will commit your changes
push the feature branch to the repository fork in your GitHub account
open a Pull Request against the upstream repository

In this process three git repositories are used:

The upstream repository: EGI-Federation/documentation
Your fork, also named origin: <your_username>/documentation
A local clone of your fork, containing references to your fork, its origin and to the upstream repository

Add an SSH key to your GitHub account

The most convenient way to authenticate with GitHub is to use SSH keys over the SSH protocol.

You can add an SSH public key to your GitHub account in the Settings on GitHub, at https://github.com/settings/keys.

Refer to Connecting to GitHub with SSH for an extensive documentation on using SSH keys with GitHub.

It’s worth to mention that your ssh public keys can easily be retrieved using a URL like https://github.com/<your_username>.keys.

In order to manage repositories over ssh, you will have to clone them via SSH, not HTTPS.

If you already have a local clone of a repository created via HTTPS, you can switch it to SSH by following Switching remote URLs from HTTPS to SSH.

Starting with the GitHub CLI

The GitHub command-line interface greatly helps with working with GitHub repositories from a terminal.

It can be installed using the packages available on their homepage. There is also a manual.

Once installed you will have to start by setting up authentication.

# Authenticate with GitHub, favour SSH protocol
$ gh auth login
$ gh config set git_protocol ssh

Working with repositories

The easiest way is to do it via the GitHub CLI that will also clone it locally. But it can also be done via the web interface, using the fork button and then cloning it locally manually.

Fork and clone

This command will fork the repository to your GitHub account and clone a local copy for you to work with.

$ gh repo fork EGI-Federation/documentation

Clone existing fork

If you want to clone an existing fork you should use:

$ gh repo clone <your_username>/documentation

Validate the local clone

If your local clone of you fork is correctly setup you should see references to the origin and upstream repositories.

$ git remote -v
origin git@github.com:<your_username>/documentation (fetch)
origin git@github.com:<your_username>/documentation (push)
upstream git@github.com:EGI-Federation/documentation.git (fetch)
upstream git@github.com:EGI-Federation/documentation.git (push)

Run the site locally

The documentation site is built from the source files using Hugo. The repository README can be used as a reference for building instructions.

Requirements

Hugo
Node.js and other docsy theme dependencies:
- postcss-cli
- autoprefixer

These dependencies can be either installed manually or reusing a flox environment. Please see the steps below.

Installing dependencies manually

To install npm+Node.js please check the official instructions.

Everything has been tested with Node.js 12.

The dependencies of the docsy theme can be installed as follows:

# From the root of the repository clone
$ npm ci

Hugo can be installed following the official documentation.

Hugo (extended) releases can be downloaded at the Hugo releases page. The recommended version for Hugo is specified under the GitHub Action in .github/workflows/hugo_version.txt.

Reuse the Flox environment

Flox is a virtual environment and package manager all in one. We provide a flox environment in our GitHub repository in a way that it is easier for everybody to work with the same software dependencies and contribute to this repository.

After installing flox you can reuse the provided environment with:

# From the root of the repository clone
$ flox activate
# Then install docsy dependencies with
$ npm ci

Installing pre-commit hooks

Git hooks are small bits of code which run during parts of the git commit process. In particular the pre-commit hook runs before committing your changes, in order to enforce contribution guidelines, code quality and style conventions, etc.

The pre-commit framework is used to manage the pre-commit hooks in this repository, and should be installed before making your contribution:

$ pip install pre-commit
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

See .pre-commit-config.yaml in the repository for more details of which hooks are enabled.

Building the site

To build and run the site, from the repository root:

$ git submodule update --init --recursive --depth 1
$ hugo --minify

Testing the site locally

To launch the site locally, from the repository root:

$ hugo serve -D

The site is available locally at: http://localhost:1313/.

Branches and commits

You should submit your patch as a git branch ideally named with a meaningful name related to the changes you want to propose. This is called a feature branch (sometimes also named topic branch). You will commit your modifications to this feature branch and submit a Pull Request (PR) based on the differences between the upstream main branch and your feature branch.

Create a feature branch

Try to avoid committing changes to the main branch of your clone to simplify management, creating a dedicated feature branch helps a lot. Try to pick a meaningful name for the branch (my_nice_update in the example).

# This should be done from the up-to-date main branch
# Read furthermore to see documentation on updating a local clone
$ git checkout -b my_nice_update

Write changes

The documentation being made of plain text files you are free to use whatever text editor or Integrated Development Environment (IDE) suits you, from neovim to Visual Studio Code.

Some environments may provide you plugins helping with syntax or offering a preview, they are worth checking.

Be sure to commit files with having been formatted using Prettier as documented in our style guide.

Commit changes

It is the best practice to have your commit message have a summary line that includes the issue number, followed by an empty line and then a brief description of the commit. This also helps other contributors understand the purpose of changes to the code.

 #3 - platform_family and style

 * use platform_family for platform checking
 * update notifies syntax to "resource_type[resource_name]" instead of
 resources() lookup
 * GH-692 - delete config files dropped off by packages in conf.d
 * dropped debian 4 support because all other platforms have the same
 values, and it is older than "old stable" debian release

# Select the modified files to be committed
$ git add files1 path2/
# Commit the changes
$ git commit -m <commit_message>

Push feature branch to the fork in preparation of a PR

From inside a feature branch you can push it to your remote fork.

# Ask git to keep trace of the link between local and remote branches
$ git push --set-upstream

Once done, the output will show a URL that you can click to generate a Pull Request (PR). Accessing GitHub upstream of forked repositories may also propose you to submit a PR.

If needed GitHub CLI can also be used to prepare the PR:

$ gh pr create <your_username>:<feature_branch> --web

Previewing a pull request

If a repository maintainer adds the label safe for preview to a pull request it will be possible to preview it using a pull request-specific URL: https://docs.egi.eu/documentation/[PR_NUMBER]

The preview can be used as an alternative to testing a pull request locally, and the preview can easily be shared with other contributors.

Only collaborators having write permission to the repository are able to mark a pull request as safe for review.

This should be carefully considered, especially for external and first time contributors.

Update local feature branch with changes made on the PR

Once you PR have been opened it will be reviewed, and reviewers can propose and commit changes to your PR. If you need to make further changes be sure to update the local clone with the remote changes.

# Retrieve changes made on your PR in the upstream repository
$ git pull

Then you can commit new changes and push them to your remote fork.

Update repository clone with the upstream changes

# If you are still in a branch created for a previous PR, move to main
$ git checkout main
# Get the latest data from the upstream repository
$ git fetch upstream
# Update your local copy with this data
$ git rebase upstream/main main
# Update your remote GitHub fork with those changes
$ git push

Update local feature branch with changes made on the main branch

In case the main branch evolved since the feature branch was created, it may be required to merge the new changes in the feature branch.

It can easily be done via the PR page on the GitHub web interface, but it can also be done in your repository clone using git rebase.

# Retrieve changes made in the upstream repository
$ git fetch upstream
# Check out the feature branch
$ git checkout feature_branch
# Apply the new changes on main to your feature branch
$ git rebase upstream/main

In case some files have been changed on both sides you will have to merge the conflicts manually.

Running checks from GitHub actions locally

The repository leverages GitHub Actions to do automatic checks. These are encoded in the pre-commit hooks described above. In order to run these checks locally on the full repository, run

pre-commit run --all

Checks are declared in the Megalinter configuration file.

It’s possible to run those linters locally, it can be useful to test and debug why they are reporting errors, and test without waiting on the automatic checks.

To save time, we recommend running the specific you are interested in, but as documented later for Check-Spelling, you can use act to run the real GitHub actions workflows.

Running markdownlint locally

markdownlint-cli can be installed locally on some platforms, in that case it can be used like this:

$ markdownlint -c .github/linters/.markdownlint.json \
 content/en/about/_index.md

If you cannot or don’t want to install it locally, you can rely on using Docker and GitHub Packages:

$ docker run -v $PWD:/workdir:ro --rm -i ghcr.io/igorshubovych/markdownlint-cli:latest \
 --config .github/linters/.markdownlint.json \
 content/en/about/_index.md

Running markdown-link-check locally

Deprecated

This is deprecated in favour of Lychee

You can use Docker and GitHub Packages:

$ docker run -v $PWD:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable \
 --config /tmp/.github/linters/mlc_config.json \
 /tmp/content/en/about/_index.md

Running Check-Spelling locally

For spelling, it may be easier to rely on a spell checker integrated in your content editor.

Nevertheless, if you are adventurous, you can use act, that will use docker to run the checks locally.

While the spell check should work, other part of the job interacting with GitHub will likely fail, like when errors are identified, so be sure to properly scan through the command output.

# Listing available jobs
$ act -l
# Running the spelling job
$ act -j spelling

Running Super-Linter locally

Deprecated

This is deprecated in favour of Megalinter

Should you want to do this, Super-Linter can be run locally.

You can try using act:

# Listing available jobs
$ act -l
# Running the lint job
$ act -j super-lint

If it doesn’t work as expected, or if you prefer another solution, you should look at the Super-Linter documentation for running locally.

Clone PR to edit/test/review locally

It’s possible to clone a Pull Request to a local branch to test it locally. It’s done using the PR number.

# List available PR and their identifiers.
$ gh pr list
# Clone specific PR, updating submodules
$ gh pr checkout XX --recurse-submodules

Once done it’s possible to build and run the site locally:

# From the root of the repository clone
# Here on MacOS X, adapt depending on your platform
$ hugo serve -D

The documentation will then be accessible on http://localhost:1313.

People having write access to the repository hosting the branch related to the PR (ie. usually the PR author) will be able to add and edit files.

# From the local clone of the repository
$ gh pr checkout XXX --recurse-submodules
$ vim yyy.zz
$ git add yyy.zz
$ git commit yyy.zz -m <commit_message>
$ git push

Update a local clone of a PR

# It will ask you to merge changes
$ git pull

Then you can refer to the README.md to see how to test it locally.

In case the PR got commits that were forced pushed you may have troubles, in that case it may be easier to delete the local branch and do another checkout of the PR.

Clean a local clone of a PR

In case you have troubles updating the local clone, as it can happens if changes were forced pushed to it, it maybe easier to delete the local copy of the PR and recreate it.

# Switch to main branch
$ git checkout main
# Check local branches
$ git branch -vv
# Delete a specific branch
$ git branch -d <branch_name>
# If you need to force the deletion use -D
$ git branch -D <branch_name>

Using stashes

Sometimes we realise just before committing a change that we are not in the correct branch (ie. that we forgot to create a dedicated feature branch), when this happens git stash can be helpful.

# Saving a change
$ git stash save <optional message>
# Creating the forgotten branch
$ git checkout -b <my_feature_branch>
# Reviewing the saved changes, use TAB completion
$ git stash show <TAB>
# Applying the saved changes, use TAB completion
$ git stash pop <TAB>
# Review the changes to be committed
$ git diff

If you already committed your change(s) you may have to look at git reset.

# Viewing the diff of the two last commits
$ git log -n 2 -p
# Reverting the last change, keeping the change in the local directory
$ git reset HEAD^

About: Style Guide

Mon, 01 Jan 0001 00:00:00 +0000

General recommendations

All files and folders should be lower case
EGI Services should be named exactly as in the EGI Services Portfolio
Acronyms should be used only when it makes sense
Service names should never be replaced by acronyms
When introducing services, link to the public page of the service, if any:

[EGI Cloud Compute](https://www.egi.eu/service/cloud-compute/)

Markdown writing guidelines

Documentation pages have to be written in Markdown, compliant with CommonMark and GitHub Flavored Markdown.

Basic rules

Headings must start at level 2 (##), as level 1 (#) is the title of the page
Lines should be wrapped at 80 characters
Sentences must be separated by one space only
Indent is made with spaces, not with tabs
Bullet lists should be using - not *
Numbered lists should be using 1. for each line (automatic numbering)
Indent secondary (and following) level lists with 2 spaces
Lines must end with a Line Feed character (\n)
Files must end with an empty line
Shell examples should include a prompt ($ or >) in front of commands, to make it easy to understand which is the command and which is the output
Commands in shell examples should be broken into multiple lines of 80 characters or less, using a trailing backslash character (\) on each line that continues on the next
Never break command output in shell examples to multiple lines, instead use style exceptions when necessary

Tip

Syntax examples that can be used in the files are documented in the shortcodes section.

Automating formatting and checking

Style should be enforced via the usage of Prettier. Prettier can be integrated with various editors.

With VIM/neovim it can be used via a plugin like ALE as described in the official documentation.
With VisualStudio Code please see the official documentation

Configuration is provided in .prettierrc, options can be set as follows:

--print-width 80 --tab-width 2 --prose-wrap always

When a contribution is received (via a pull request), the proposed changes are checked using various linters.

General writing guidelines

Follow the guidelines below to ensure readability and consistency of the EGI documentation. These are based on the OpenStack documentation writing style guidelines, released under a Creative Commons license.

Tip

Short and simple sentences are easier to read and understand.

Use standard English

Use standard British English (UK) throughout all technical publications. When in doubt about the spelling of a word, consult the Merriam-Webster’s Collegiate Dictionary and the IBM developerWorks editorial style guide.

Be clear and concise

Follow the principles of minimalism. If you can describe an idea in one word, do not use two words. Eliminate all redundant modifiers, such as adjectives and adverbs.

Write objectively

Do not use humor, jargon, exclamation marks, idioms, metaphors, and other colloquialisms.

Describe the most common use case first

Put the most common case in the main clause and at the beginning of a paragraph or section. You can introduce additional use cases by starting a sentence with “however” or “if”.

Write in active voice

In general, write in active voice rather than passive voice. Active voice identifies the agent of action as the subject of the verb, usually the user. Passive voice identifies the recipient (not the source) of the action as the subject of the verb.

Active-voice sentences clarify the performer of an action and are easier to understand than passive-voice sentences. Passive voice is usually less engaging and more complicated than active voice. When you use passive voice, the actions and responses of the software can be difficult to distinguish from those of the user. In addition, passive voice usually requires more words than active voice.

Examples

Do not use	Use
After the software has been installed, the computer can be started.	After you install the software, start the computer.
The Configuration is saved when you click OK.	Click OK to save the configuration.
A server is created by you.	Create a server.

However, passive voice is acceptable in the following situations:

Using active voice sounds like you are blaming the user. For example, you can use passive voice in an error message or troubleshooting content when the active subject is the user.

Example

Do not use	Use
If the build fails, you probably omitted the flavor.	If the build fails, the flavor might have been omitted.

The agent of action is unknown, or you want to de-emphasize the agent of action and emphasize the object on which the action is performed.

Example

Do not use	Use
The product, OS, or database returns the messages.	The messages are returned [by the database].

Recasting the sentence in active voice is wordy or awkward.

Example

Do not use	Use
In 2009, engineers developed a software that simplifies the installation.	A software that simplifies the installation was developed in 2009.

Write in second person

Users are more engaged with documentation when you use second person (that is, you address the user as “you”).

Writing in second person has the following advantages:

Second person promotes a friendly tone by addressing users directly.
Using second person with the imperative mood (in which the subject you is understood) and active voice helps to eliminate wordiness and confusion about who or what initiates an action, especially in procedural steps.
Using second person also avoids the use of gender-specific, third-person pronouns such as he, she, his, and hers. If you must use third person, use the pronouns they and their, but ensure that the pronoun matches the referenced noun in number.
Use first person plural pronouns (we, our) judiciously. These pronouns emphasize the writer or EGI rather than the user, so before you use them, consider whether second person or imperative mood is more “user-friendly.” However, use “we recommend” rather than “it is recommended” or “EGI recommends”.

Tip

You can use “we” in the place of EGI if necessary.

Do not use first person to avoid naming the product or to avoid using passive voice. If the product is performing the action, use third person (the product as an actor). If you want to de-emphasize the agent of action and emphasize the object on which the action is performed, use passive voice.

The first-person singular pronoun “I” is acceptable in the question part of FAQs and when authors of blogs or signed articles are describing their own actions or opinions.

Important

Do not switch person (point of view) in the same guide or on the same page.

Examples

Do not use	Use
Creating a server involves specifying a name, flavor, and image.	To create a server, specify a name, a flavor, and image.
To create a server, the user specifies a name, flavor, and image.	To create a server, you specify a name, flavor, and image.

Use the present simple tense

Users read documentation to perform tasks or gather information. For users, these activities take place in their present, so the present tense is appropriate in most cases. Additionally, the present tense is easier to read than the past or future tense.

Example

Do not use	Use
The product will prompt you to verify the deletion. After you log in, your account will then begin the verification process.	The product prompts you to verify the deletion. After you log in, your account begins the verification process.

Tip

Use the future tense only when you need to emphasize that something will occur later (from the users’ perspective).

Do not humanize inanimate objects

Do not give human characteristics to non-human subjects or objects.

Example

Do not use	Use
This guide assumes…	This guide describes…

Avoid personification

Do not express your fears or feelings in technical writing. Avoid the adverbs such as “probably”, “hopefully”, “basically”, and so on.

Avoid ambiguous titles

Each title should include a clear description of the page’s or chapter’s subject.

Example

Do not use	Use
Update metadata	Update object metadata

Eliminate needless politeness

Do not use “please” and “thank you” in technical documentation.

Write positively

Write in a positive tone. Positive sentences improve readability. Try to avoid the following words as much as possible:

Examples

Do not use	Use
damage	affect
catastrophic	serious
bad	serious (or add explanation)
fail	unable to
kill	cancel or stop
fatal	serious
destroy	remove or delete
wrong	incorrect or inconsistent

Do not use contractions

Generally, do not contract the words.

Examples

Do not use	Use
can’t	cannot
don’t	do not

Do not overuse this, that, these, and it

Use these pronouns sparingly. Overuse contributes to readers’ confusion. To fix the ambiguity, rephrase the sentence.

Example

Do not use	Use
The monitoring system should perform regular checks to verify that the Ceph cluster is healthy. This can be achieved using the Ceph health command.	The monitoring system performs regular checks to ensure the Ceph cluster is functioning correctly. Use the Ceph health command to run a health check.

Tip

You can also fix the ambiguity by placing a noun modifier immediately after the pronoun.

Do not split infinitives

Do not place modifiers between “to” and the verb. Typically, placing an adverb or an adjective between “to” and a verb adds ambiguity to a sentence.

Avoid prepositions at the end of sentences

As much as possible, avoid trailing prepositions in sentences by avoiding phrasal verbs.

Example

Do not use	Use
The image registration window will open up.	The image registration window opens.

To fix the verb-preposition constructions, replace them with active verbs.

Examples

Do not use	Use
written up	composed
pop up	appear

Use consistent terminology

Use consistent terms across all content. Avoid multiple variations or spellings to refer to the same service, function, UI element, and so on.

Use spelling and grammar checking tools

Run text through spelling and grammar checking tools, if available. Correcting mistakes, especially to larger sections of new content, helps eliminate rework later.

Lists

When reading a document for the first time, users scan through pages stopping only on the content that stands out, such as titles, lists, links, diagrams, and so on. Lists help to organize options, as well as help readers to find information easily.

When listing items, follow these guidelines:

Use a bulleted list for options. Create a bulleted list when you need to describe more than three options.
Use a numbered list for steps.
Use a definition list to explain terms or describe command-line parameters, options, or arguments.
Use a colon at the end of the sentence that introduces a list.
Use the same grammatical structure (aka parallel structure) for all items in a list.
Start each option with a capital letter.

When listing options in a paragraph, add and or or before the last item in a list. Use a serial (Oxford) comma before these conjunctions if they connect three or more items.

Punctuation in lists

In bulleted lists:

If you list individual words or phrases, do not add a period at the end of each list item.
If you use full sentences, add a period at the end of each sentence.
If your list includes both individual words or phrases and full sentences, be consistent and either add or do not add periods to all items.

In numbered lists:

Add periods at the end of steps.
If an item of a numbered list is followed by a code block that illustrates how to perform the step, use a colon at the end.

Adding exceptions for style violations

Successfully passing the checks is a firm requirement, but for the following cases it is possible to add exceptions and bypass some checks in Markdown files:

When in-line HTML must be used (e.g. in tables, or when no other proper solution is available)
When the same procedure needs to be described for multiple platforms, and the automatic checker flags it as duplicate content

Important

Exceptions should only be used when there are no other choices, and should be confined to the smallest possible block of Markdown code.

Dealing with in-line HTML tags

In some specific cases it is impossible to use anything but in-line HTML tags:

Presentation page leveraging bootstrap CSS classes or other advanced features
Using special formatting for the information presented (e.g. a list in a table cell)

Blocks with in-line HTML tags should be preceded by a HTML comment starting with markdownlint-disable to disable the no-inline-html check, as in the following example:

Tip

When having a table is not absolutely necessary, use a different construct to present the information.

<!-- markdownlint-disable no-inline-html -->

| Action | OCCI | OpenStack | This is a very long column with important data |
| ----------- | ------------------------ | ---------------------- | ---------------------------------------------- |
| List images | `occi -a list -r os_tpl` | `openstack image list` | <ul><li>Lorem</li><li>ipsum</li></ul> |

<!-- markdownlint-enable no-inline-html -->

Tip

Do not forget to follow up with a HTML comment starting with markdownlint-enable to re-enable the no-inline-html check.

Important

Always use the tag that is providing the proper semantic: e.g. for a list use <ul> and <li>, not <br />.

Dealing with duplicate content

When the same procedure needs to be described for multiple platforms, or when the same code has to be exemplified for multiple languages, it is possible that the automatic checkers will flag these as duplicates.

For example, describing the following procedure will result in duplicates being reported:

{{< tabpanex >}}

{{< tabx header="Linux" >}}
 To run the FedCloud client in a container, make sure
 [Docker is installed](https://docs.docker.com/engine/install/#server),
 then run the following commands:

 ```shell
 $ docker pull tdviet/fedcloudclient
 $ docker run -it tdviet/fedcloudclient bash
 ```
{{< /tabx >}}

{{< tabx header="Mac" >}}
 To run the FedCloud client in a container, make sure
 [Docker is installed](https://docs.docker.com/desktop/mac/install/),
 then run the following commands:

 ```shell
 $ docker pull tdviet/fedcloudclient
 $ docker run -it tdviet/fedcloudclient bash
 ```
{{< /tabx >}}

{{< tabx header="Windows" >}}
 To run the FedCloud client in a container, make sure
 [Docker is installed](https://docs.docker.com/desktop/windows/install/),
 then run the following commands:

 ```shell
 > docker pull tdviet/fedcloudclient
 > docker run -it tdviet/fedcloudclient bash
 ```
{{< /tabx >}}

{{< /tabpanex >}}

This type of content should be preceded by a HTML comment that disables the check for duplicates, and followed by another HTML comment that enables it again.

<!--
// jscpd:ignore-start
-->

...content with duplicates here...

<!--
// jscpd:ignore-end
-->

About: Shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

In addition to the formatting support provided by Markdown, Hugo adds support for shortcodes, which are Go templates for easily including or displaying content (images, notes, tips, advanced display blocks, etc.).

For reference, the following shortcodes are available:

Highlighted paragraphs

This is achieved using Docsy shortcodes.

Placeholders

The following code:

{{% pageinfo %}} This is a placeholder. {{% /pageinfo %}}

Will render as:

This is a placeholder.

Information messages

The following code:

{{% alert title="Note" color="info" %}} This is a Note. {{% /alert %}}

Will render as:

Note

This is a Note.

Warning messages

The following code:

{{% alert title="Important" color="warning" %}} This is a warning.
{{% /alert %}}

Will render as:

Important

This is a warning.

Code or shell snippets

The code or instructions should be surrounded with three backticks, followed by an optional highlighting type parameter.

The supported languages are dependent on the syntax highlighter, which depends itself on the Markdown parser.

Note

Hugo uses the goldmark parser, which relies on Prism syntax highlighting.

The following Markdown creates a shell excerpt:

```shell
$ ssh-keygen -f fedcloud
$ echo $HOME
```

Will render as:

$ ssh-keygen -f fedcloud
$ echo $HOME

Tip

If you click the Copy button in the top-right corner of a shell example, all commands in that block are copied to the clipboard. The prompt in front of each command, and any command output is not copied.

Note

In case the command(s) in your shell example cause the introduction of a horizontal scroll bar, consider breaking the command(s) into multiple lines with trailing backslashes (\). However, you should never break command output to multiple lines, as that makes understanding the output, and recognizing it in real life, very difficult.

Code in multiple languages

This is also achieved using Docsy shortcodes.

When you need to include code snippets, and you want to provide the same code in multiple programming languages, you can use a tabbed pane for code snippets:

{{< tabpane >}}
{{< tab header="C++" lang="C++" >}}
#include <iostream>
int main()
{
 std::cout << "Hello World!" << std::endl;
}
{{< /tab >}}
{{< tab header="Java" lang="Java" >}}
class HelloWorld {
 static public void main( String args[] ) {
 System.out.println( "Hello World!" );
 }
}
{{< /tab >}}
{{< tab header="Kotlin" lang="Kotlin" >}}
fun main(args : Array<String>) {
 println("Hello, world!")
}
{{< /tab >}}
{{< tab header="Go" lang="Go" >}}
import "fmt"
func main() {
 fmt.Printf("Hello World!\n")
}
{{< /tab >}}
{{< /tabpane >}}

Will render as:

#include <iostream>
int main()
{
 std::cout << "Hello World!" << std::endl;
}

class HelloWorld {
 static public void main( String args[] ) {
 System.out.println( "Hello World!" );
 }
}

fun main(args : Array<String>) {
 println("Hello, world!")
}

import "fmt"
func main() {
 fmt.Printf("Hello World!\n")
}

Content with multiple variants

When you need to include multiple variants of the same content, other than code snippets in multiple programming languages, you can use the following shortcode:

{{< tabpanex >}}

{{< tabx header="Linux" >}}

You can list all files in a folder using the command:
```shell
$ ls -a -l
```
{{< /tabx >}}

{{< tabx header="Mac" >}}
To get a list of all files in a folder, press **Cmd** + **Space** to open
a spotlight search, type terminal, then press Enter. In the terminal window
then run the command:

```shell
$ ls -a -l
```

{{< /tabx >}}

{{< tabx header="Windows" >}}

You can list all files in the current folder using the command:

```shell
> dir
```

or you can use PowerShell:

```powershell
> Get-ChildItem -Path .\
```

{{< /tabx >}}

{{< /tabpanex >}}

Will render as:

You can list all files in a folder using the command:

$ ls -a -l

To get a list of all files in a folder, press Cmd + Space to open a spotlight search, type terminal, then press Enter. In the terminal window then run the command:

$ ls -a -l

You can list all files in the current folder using the command:

> dir

or you can use PowerShell:

> Get-ChildItem -Path .\

Tip

You can include any valid markdown content in each tab, including code or shell snippets.