Adding a New Article

Thanks for your interest in submitting documentation articles! This article shows you how to add a new article to the TrueNAS Documentation Hub. All that is required is a GitHub account and your favorite text editor. Taking screenshots for your article is also recommended.

To add an article, construct a bundle that contains your text file and any images, then open a pull request on the repository. There is an Article Template available that can simplify creating your article.

Creating an Article Bundle

Find a place on your local system to create a directory for your article. Name the directory according to the title of your article.

ArticleBundle

Open the directory and create a new file called index.md. This file contains all the text for your article.

Writing the Article

The first few lines of the index.md are reserved for an intro block called the “front matter” that contains the document title and other information. For example, this article uses basic front matter:

---
title: "Adding a New Article"
weight: 20
---

After setting the front matter, continue writing your article. Raw text is supported, or you can add Markdown syntax. Markdown is designed to be easy to write and read, but also supports directly adding HTML elements. See the Style Guide for syntax help and other suggestions for writing the article. You can generally style the article however you like, but please be aware that other contributors can review the article and change the styling.

Adding Images

If you want to include screenshots of the TrueNAS User Interface with your article, add these files to your article bundle. Be sure to have unique names for each image file.

AddingImages

Uploading the Article Bundle

Open the User Recommendations section of the repository.

UploadImages

Click Upload files and drag and drop the article bundle directory into the repository. GitHub shows all the files to upload.

AddNewArticlePhotosRepo

Opening a Pull Request

Forking the repository might be needed as part of opening a Pull Request.

Make sure all your files have been uploaded then scroll down to the Commit changes section and write a summary and description of your changes. Select Create a new branch for this commit and start a pull request. and click Propose changes. GitHub can take a few moments to process the files.

Make sure you’re happy with the summary and description of your article, then click Create pull request.

After the pull request is created, the repository automatically builds a preview of the documentation site that has your changes included. The link to this preview is added to the Pull Request after the build completes.

ArticlePreview

Other contributors will review and merge your article!