Contribute to docs prerequisites

This page covers the tools and dependencies you need to install and set up before you contribute to our docs. This page discusses:

Git
GitHub
Python
Visual Studio Code
Using your CLI
MkDocs and its dependencies
Markdown

Tip

If you prefer not to use Git in a command line interface (CLI) there are some other options.

GitHub offers its own GitHub Desktop tool.
Atlassian owns and maintains Sourcetree, a Git client for both Windows and Mac.
Visual Studio Code and other code editors have their own source control GUI. In Visual Studio Code, locate the Source Control item in the global left-hand sidebar. Read their docs here.

Git

We version- and source-control our docs using docs-as-code, which requires a working knowledge of Git. We recommend you learn the basics of Git before contributing. You can find plenty of good Git resources on YouTube, Udemy, Coursera, EdX, and elsewhere.

Here's a summary of the Git commands most commonly used:

git pull will download all data from the remote (in our case, GitHub) copy of your branch to your local machine.
git status will confirm the current state of any files you have modified on your branch, including staged and unstaged files (i.e. files you want Git to index for commits).
git add instructs Git that the selected files are to be staged for commit. Files that are not added will not be included in any commits or pushes to the remotr (GitHub) repo. Use git add . to signal that you're including all modified files on your current path as part of this add. If you wish to include specific files as part of an add, then ensure you change directory to the correct path, and specify each file as part of a comma-separated list after the command. For example git add "file_1.md", "file_2.md" etc.
git commit commits staged files for a push. Only files that are committed will be pushed.
git push pushes your commits up to the remote copy of your branch in the repo.

For more information about GitHub and using Git commands in the command line, read About Git

GitHub

Create a GitHub account.
- Your GitHub account is your GitHub user account. While you can associate it with GitHub organization accounts, such as Matillion, your GitHub account is retained by you if you leave Matillion and you will be disconnected from the Matillion GitHub organization.
Request access to "GitHub Enterprise Organization - Matillion" via Lumos, and enter your Matillion email address.
Note
- It's recommended that you refrain from using "matillion" in your GitHub username.
- You can set your Matillion email or your personal email as your primary email. Both can be hidden.
- Set a unique, secure password for your account.
Follow these steps to prepare your GitHub account for joining the Matillion organisation.
Link your GitHub account to Matillion's Okta SSO for authentication. For more information, read Okta Authentication.

SSH keys

You'll need at least one SSH key in your GitHub account. Read Generating a new SSH key and adding it to the ssh-agent

Python

Ensure you have Python and Pip installed on your machine. In both the Windows and Mac suggestions below, the Python installations will include Pip.

For Windows users, your best bet is downloading Python from python.org. We recommend you choose a latest stable version.

Depending on your organization, you may need to untick the Use admin privileges when installing py.exe box.
Ensure the Add python.exe to PATH box is ticked ✅.

For Mac users, your best bet is downloading Python from python.org. We recommend you choose a latest stable version.

In the installation wizard, click Continue until you reach the Installation Type and then click Customise and ensure, as per the GIF below, that the relevant boxes are ticked ✅.

Visual Studio Code

Download and install Visual Studio Code. Alternatively, you can use another code editor.

When making changes to the docs, you'll use Visual Studio Code or your preferred code editor.

Using your CLI

Some basic commands to know include:

cd <directory name> - change directory (folder) to a subfolder within your current working directory.
- e.g. cd documents and then (if you cloned the repo to your Documents folder) cd matillion-docs. You can also just use cd documents/matillion-docs.
ls - list the files and subdirectories in your current directory.
cd .. move back up by one level of directory/folder.

MkDocs

docs.matillion.com is built on the MkDocs static site generator, with Material for MkDocs as the theme. The site is then hosted via GitHub Pages.

MkDocs comes with a "local build" feature, meaning you can spin up a local version of the docs site to view any modifications you've made to the docs as they would appear on the live site.

Follow these steps to install MkDocs:

Note

You'll need to install Python and Pip if you haven't already. Read Python.
At this stage, your CLI doesn't need to point at any specific directory.

Run the following command in your CLI. Not working? Try pip3 instead of pip.

pip install mkdocs mkdocs-material mkdocs-include-markdown-plugin mkdocs-redirects mkdocs-glightbox mkdocs-open-in-new-tab mkdocs-toggle-sidebar-plugin

This installs the following tools:
- MkDocs: the static site generator we use for our documentation.
- MkDocs Material: a robust and popular theme for MkDocs. Fully open-source.
- mkdocs-include-markdown-plugin: a plugin for managing snippets.
- mkdocs-redirects: a plugin for managing URL redirects in MkDocs.
- mkdocs-glightbox: a plugin for image magnification.
- mkdocs-open-in-new-tab: a plugin for managing external links opening in a new tab.
- mkdocs-toggle-sidebar-plugin: a plugin to toggle visibility of the left nav and right-hand TOC.
Once the command has finished installing all of those tools, run:
```
mkdocs --version
```
This confirms that MkDocs installed (and should indicate that the other tools installed, too—unless you saw an error message). If you are using Windows, you may need to run the command with "python -m " beforehand, like the following:
```
python -m mkdocs --version
```

Markdown

Matillion's docs are written in Markdown. Some files also include HTML. This Markdown cheat sheet is a good place to learn the basics of Markdown. YouTube, Udemy, Coursera, ChatGPT, an many other tools can offer extensive information about both Markdown and HTML.