Setting up a local authoring environment

The Fedora Server Edition working group, Peter Boy (pboy), Stephen Daley (mowest) Last review: 2026-11-11
This method involves creating a copy of the documentation source on the local workstation. Linux and macOS are directly supported. This also includes a script for generating an exact local preview. The editing itself can be done with any editor.

This article is outdated and needs updating.

How it works

As already described in the introduction, the documentation is written in AsciiDoc and converted into HTML pages by the CMS. The Fedora Server user documentation git repository contains the documentation source text.

It includes the content as well as various scripts to build and preview the site locally. The directory structure is predefined by the docs Content Management System (Antora) and must not be changed.

It has 2 permanent versions: The "main" for the published content and "stg" for planning, development, and discussion. Temporarily, additional branches may also be present.

Members of the Fedora Server Working Group have the privilege of making changes directly in the original, central repository.

Everyone else can also copy the repository, but must save changes in their own sub-section and then generate a “pull request.” This prompts members of the working group to review the proposed changes and pull them into the central repository.

In the case of major changes, members of the working group should also first submit their proposals in a separate sub-section.

Writing tools

You can use any ASCII editor to work on the documentation files.

A particularly useful OSS Asciidoc editor is AsciidocFX. It is a Java program, very easy to install, and provides both an integrated directory access, a toolbar with the most common AsciiDoc formatting similar to a Word editor and an integrated instant preview.

Creating a new documentation article

An annotated template is available to make things easier. Download it and save it in the appropriate directory with a new name.

If possible, the files should be named in such a way that related files appear together in the directory listing. The most important, most differentiating parts should be at the front. For example

  • filesharing-nfs-administration.adoc

  • filesharing-nfs-installation.adoc

  • filesharing-samba-administration.adoc

  • filesharing-samba-installation.adoc

The titles should follow this pattern as far as possible and avoid redundant parts such as "How to install …​"

  • File sharing with NFS - Installation

  • File sharing with NFS - Administration

  • File sharing using Samba - Installation

  • File sharing using Samba - Administration

All file names are in lower case.

Preparations

  1. Create a local subdirectory where the files of the documentation should be stored, and make it your default. We use fedora-server-docs in your home directory throughout this guide

    […]$ mkdir ~/fedora-server-docs
[…]$ cd    ~/fedora-server-docs

  2. Still in your default working directory, clone fedora-server repository

    […]$ git clone https://git@pagure.io/fedora-server.git -o upstream

    Git will copy the complete server repo including all branches, specifically "main" and "stg" mentioned above, into a local repo on your local workstation (into .git/ located in your default directory).

    Git does "tag" the cloned repo as remote repo "upstream".

    At the same time it checks out the default branch "''main''" into your ''working directory'' (i.e. ~/fedora-server-docs in the above example). Therefore, when the operation terminates, you will find in your current default directory, which is now your ''working directory'', some files, e.g. README.md, docsbuilder.sh and preview.sh and a directory docs. The latter contains the content.

    If you leave off "./" at the end, git creates another directory in your default directory with the name of the repository, i.e. fedora-server. And this directory is then the "working directory" to the repository. This can be useful if you want to keep track of different fedora docs projects in one directory.

  3. In your browser go to https://pagure.io/fedora-server/, log in and create a Fork. Once you have done it, the button will read View fork. Switch to your fork and click on Clone and you will see 2 addresses you can use to clone (copy) the content to your local default directory

    ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git
https://git@pagure.io/forks/[MY_FAS]/fedora-server.git

    Still in your default working directory, add the forked Repo to your remote repos.

    […]$ git remote add origin ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git

    You can use https as well. For users with a FAS account ssh is usually the better choice.

  4. You have now 2 remote repos defined. Check:

    […]$ git remote -v
origin	ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git (fetch)
origin	ssh://git@pagure.io/forks/[MY_FAS]/fedora-server.git (push)
upstream	https://git@pagure.io/fedora-server.git (fetch)
upstream	https://git@pagure.io/fedora-server.git (push)

    In your workflow you will update your local version to the latest versions of the server repository by "pulling" the content from "upstream" and upload your modifications and additions by "pushing" it to origin, i.e. to your fork. You will than create a "pull request", i.e. pick up your modifications and additions from your fork and integrate it into the generic repository ("origin"). This enables co-writers to review our work and comment on it.

  5. In your working directory build the local version and start the preview tool.

    […]$ ./docsbuilder.sh

  6. Back in your browser enter the local preview address': localhost:8080

    • You should see a local preview of the current Server documentation

Working on content

  1. Check if you are on the branch you intend to work on

    […]$ git branch
main
* stg

  2. If not, switch to the branch you want to use.

    […]$ git checkout [stg|main]

    Git will adjust and modify the content of your working directory accordingly!

  3. Before your begin to work update your working directory

    […]$ git commit -m "<YOUR COMMIT MESSAGE>"

  4. Modify content

  5. Update preview and check:

    […]$ ./docsbuilder.sh

    Preview in your browser using the address 'localhost:8080

  6. Repeat step 4 & 5 as required.

Save Your Work

Commit your work locally and then push it into your fork "origin".

  1. Check status

    […]$ git status

  2. Add files to commit stage as appropriate

    […]$ git add <FILENAME>

  3. Commit locally

    […]$ git commit -m "<YOUR COMMIT MESSAGE>"

  4. Transfer your fork of fedora server to the repository

    […]$ git push origin [main|stg]

  5. In your browser open https://pagure.io/fedora-server, login, switch to your fork and create a pull request.

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