Updating Content

Changes wanted! Contributing changes to the TrueNAS documentation has never been easier. The Documentation Hub has been specifically built to allow users to quickly propose changes to the content without having to install any special applications. All that is required is to have a GitHub account and a basic understanding of Markdown.

The repository automatically builds a preview site for each open Pull Request (PR). The link to this preview site is added to the PR as a comment. The preview updates with any changes to the pull request, so you can always see an accurate preview of the changes you’re making to the website.

Making Quick Changes to an Article

(Video URL: https://www.truenas.com/docs/files/docsquickedit.mp4)

If you find text that needs to be fixed or improved in an article, click Edit this page to view the article source text in a new browser tab. To check your changes for bugs in the Markdown or HTML syntax, switch to the Preview changes tab. The preview renders generic Markdown, but won’t render any Hugo-specific syntax. You’ll need to log in to your GitHub account to propose any changes.

Replacing an Image

To update an existing image, click Edit this page and find the image location and name in the article source text. Make sure your replacement image has the same name as the image to be replaced.

In the repository, click Code and go to the image location in the repository. Images are located in either the /static/images/ directory or are in the same location as the article text file as part of an article bundle.


Click Upload files and either drag and drop your image or open the file browser to select your image. As long as the new image name is the same as the old image, the old image is replaced and the article automatically uses the new image.

Editing an Included File

Some article content comes from a separate include statement. This statement pulls in content from a different location and allows using common text in multiple website articles simultaneously. Updating an _include/ file updates the content in every affected article!

An example of this is in the Cron Jobs article. The expandable Advanced Scheduler content is pulled from another location in the repository (content/archive/AdvancedScheduler.md). The AdvancedScheduler.md snippet is also included in Cloud Sync Tasks and other Tasks content.

Clicking the Edit this Page link opens the article markdown file, but only these lines are visible for the included content (the \ characters are added to prevent rendering the shortcodes):

{{\< expand "Advanced Scheduler" "v" >}}
{{\< include file="/static/includes/AdvancedScheduler.md" >}}
{{\< /expand >}}
(Remove the escaping backslashes \)

The expand and /expand shortcodes handle the expansion/collapse section of the document and don’t need to change. The include statement is within the expandable element: {{/< include file="/static/includes/AdvancedScheduler.md" >}}.

The repository file static/includes/CORE/AdvancedScheduler.md.part contains the documentation for this section. To update this section, edit the .md.part file. Remember that this snippet file is used in multiple documents, so only content that generally applies is included in the snippet. Changes that are specific to a certain piece of content are added directly to that article.

Master and Version Branch Differences

TrueNAS documentation uses branches to organize content related to specific software releases and updates, for example the 24.04 and 23.10 SCALE branches of the Documentation Hub.

  • Content changes in the master branch result in changes to the TrueNAS SCALE Nightly Development Documentation content. To make changes in the master branch, create a simple copy (“fork”) of the main repository, select that forked master as the base for your changes. Do not make changes directly to the master branch of the Documentation Hub repository.

  • To make content changes in the 24.04 branch, create a fork of the main repository and check that 24.04 is listed as the base. This ensures that approved modifications will be added to the TrueNAS SCALE 24.04 (Dragonfish) Documentation content.

  • To make content changes in the 23.10 branch, create a fork of the main repository and check that 23.10 is listed as the base. This ensures that approved modifications will be added to the TrueNAS SCALE 23.10 (Cobia) Documentation content.

Fork the Repo

To submit a change, create a fork of the main repository, edit your copy, then propose merging your changes back into the main repository. To start, click the Edit this Page link in the top right of the site.


To fork the repo to your GitHub account, click the green Fork this repository button.


Syncing an Existing Fork

When you already have a fork of the documentation repository, it is recommended to sync your fork before continuing on to make changes:

  • Open your fork repository, typically found by opening the GitHub profile drop down and clicking Your repositories.
  • Find the sync status bar and click Pull request.
  • Set the base repository to your fork and the head repository to truenas/documentation. You might need to click compare across forks first. CompareFork
  • Click Create pull request and continue to merge the pull request.

Edit the page as needed.


When the changes are complete, add a quick overview of what changes were made in the description box, and click the green Commit changes button.


When the page refreshes the changes are complete in your forked repository. Now you can request merging these changes main repository using a “Pull Request” (PR). Click on Pull Requests.


After the Pull Requests page opens, click on the green New Pull Request button.


Confirm that the base repository is set to truenas/documentation and base is set to master. head repository must be set to your forked repository, for example q5sys/documentation. compare needs to be set to master. Make sure these options are correct, then click the green Create pull request button to create the PR.


Describe your changes and click the green Create pull request button.


That’s it! Other contributors review and merge your changes!

As part of the review process, automation builds a preview of the Docs site with your changes. When the build is completed, a comment appears in the PR that shows the automation result. Click on Show all checks and Details to see a live demo of the site with your changes.