Edit Documentation Locally

Jocelyn Gould (korora) and Eli Ridge (egret) Last review: 2026-04-01

This guide will show you how to set up a local documentation editing environment on your computer, using a local clone.

Editing locally allows you to make complex edits to multiple pages simultaneously. It also allows you to preview edits exactly as they will appear once published on the main docs site.

This guide deals only with repositories (repos) hosted on Fedora Forge. The process will differ for repos hosted on GitLab, GitHub, or Pagure. You can find the legacy guides for the previously used hosting platforms in the contribution tools section of this website.

For explanations and references on the Fedora Docs tooling, please visit the Contribute to Fedora docs page.

Prerequisites

  • Prerequisites for Contributing to Docs section completed.

  • Git installed.

    In Fedora Linux, you can check that git is installed by running the following command:

    $ dnf install git

  • Text editor of choice installed.

    It is beneficial, but not essential, if your text editor has integrated file navigation, a terminal, and AsciiDoc syntax support.

Set up a local editing environment

  1. Create a local subdirectory where your local clone will be stored. The example uses the name "fedora-docs" but you can use any name.

    $ mkdir ~/fedora-docs
$ cd    ~/fedora-docs

  2. Use the Forge web interface to fork the repo you intend to edit. Click the Fork button on the top-right corner of the project page:

    fork button

    If prompted, enter the details to create your new fork. The default values are suitable in most cases.

  3. Configure your Forge access token and clone your remote fork to your computer. Follow the How to clone a Forge repo using the HTTPS guide to complete this.

  4. Configure the upstream repo in your local clone. You will need this to fetch updates from the upstream main docs repo.

    $ git remote add upstream https://forge.fedoraproject.org/docs/<name-of-upstream-repo>.git

    Verify it with:

    $ git remote -v

    The exact URLs may differ. But check that you have two origin entries that match your fork, and two upstream entries that match the upstream main docs repo URL. The output will resemble this:

    origin  https://forge.fedoraproject.org/<forge-user-name>/<reponame>.git (fetch)
origin  https://forge.fedoraproject.org/<forge-user-name>/<reponame>.git (push)
upstream        https://forge.fedoraproject.org/docs/<reponame>.git (fetch)
upstream        https://forge.fedoraproject.org/docs/<reponame>.git (push)

    The terms origin and upstream are not strict descriptors but commonly used names to refer to your fork and the upstream fork respectively. So you can choose different names to represent the two repos if you wish.

  5. Create a working branch:

    $ git checkout -b <branch-name-you-choose>

See here for further information on branching.

You are now ready to start writing. Consider making use of the Fedora style guide as well as the Vale tool to assist your editing.

Edit the AsciiDoc code

You can open and edit AsciiDoc files with any text editor.

Some text editors will provide three panes by default, and some will not show more than just the contents of the file that you are currently working on. Many graphical editors provide at least the folder structure and the .adoc file contents view at the same time; terminal editors will usually only show the contents of the .adoc file and may require either a second terminal window open or exiting the editor in order to run commands.

As an example configuration, you can use your text editor or IDE of choice with the following three viewing panes:

  • project folder structure.

  • project terminal window open at username@device:~/fedora-docs/name-of-project.

  • .adoc file contents window.

The above layout allows you to quickly select files, make edits, and issue git and preview commands, all within the same tool.

Preview your work

The docsbuilder script uses Podman to build a preview of your docs pages in an isolated container.

  1. In the terminal, navigate to your project folder. Run the docsbuilder script by entering this command:

    $ ./docsbuilder.sh

    A successful output will resemble this:

    ...
Watching current directory (excluding: build/|cache/|preview.pid|public/|\.git.*|4913) for changes and re-building as required. Use Ctrl C to stop.
Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...

  2. In a browser, visit http://localhost:8080.

  3. To update the preview after further edits:

    1. Ensure the script is at rest - the terminal window activity should have stopped and the last sentence read Watching current directory…​.

    2. Save the .adoc file you have been editing and observe the script complete again.

    3. Refresh the browser window.

On MacOS, the docsbuilder script uses Docker instead of Podman. You can install Docker from the official Docker Website.

See here for further information on the docsbuilder script.

Pushing your changes to your remote fork on Forge

  1. Determine the files that have been changed and added to the branch you are working on:

    $ git status

    The files in the output are known as 'untracked files', meaning that git has no idea what to do with these files or if you want them to be included in your commit.

  2. Add the changed files to your local git staging ground:

    $ git add <path-to-changed-file>

  3. Commit with a message:

    $ git commit -m <meaningful-name-reflecting-what-you-changed>

  4. Push your changes:

    $ git push origin <branch-name>

You are now ready to open a pull request (PR).

PR checklist

  • Spelling and grammar checked.

  • Metadata and author tags entered.

  • Tested and previewed using the s/docsbuilder/docsbuilder.sh/ script.

Opening a pull request

On the Forge web interface, navigate to your fork’s repo and the branch you have been working on. Click on the New Pull Request button.

Explanations

Branching

At its most basic level, branching is simply taking a snapshot of the main line of the repo and making changes to that branch. This keeps what you’re working on separate from what others are working on and allows for multiple changes to be merged into the main branch. After you have made your changes to the files and committed those changes to your origin repo, you can then open a pull request to have your changes merged into the main branch and published on the docs site.

The docsbuilder script and Podman

The docsbuilder script is present in your local clone’s project folder by default. Running the script starts the Antora static site generator locally on your device within an isolated container. There is no requirement to install Antora or any other web development tools on your device.

Podman is an open source container tool similar to Docker. When you run the docsbuilder.sh script, Podman will download the Antora parser to your local machine as a container. Once you are done with the container, if you wish to remove it, simply run podman image rm antora. There is no harm in leaving the container on your system if you are working on a lot of docs. This will allow you to save some bandwidth on the hosting server for the image.

Want to help? Learn how to contribute to Fedora Docs ›