intro-docs-contrib (#59)

WIP pull request for ticket [#11](docs/tickets#11), the introduction page for contributing to Fedora Docs.

Summary of changes so far:

- added small motivational paragraph
- suggest title streamline
- updated editing approaches to encourage local workflow
- reordered tools to have local workflow as the first item
- added links to local and web editing guides
- added visual contributor journey diagram
- added explanation diagrams for the site and for review process
- added various other explanations
- general revisions
- removed tool section on direct edit to upstream

Co-authored-by: Eli Ridge <>
Reviewed-on: docs/team-docs#59
Reviewed-by: Peter Boy <pboy@noreply.forge.fedoraproject.org>

.gitignore

@@ -3,3 +3,6 @@ gl-code-quality-report.json
 build
 cache
 public
+
+# created when the docsbuilder local preview is running
+preview.pid

README.md

@@ -1,70 +1,25 @@
-# Fedora Docs documentation
+# Fedora Docs Team Documentation
 
-This repository contains a minimal source structure for a new Fedora Docs source.
+Team and contributor documentation for the Fedora Docs Team.
 
-## Content of this repo
+## Published documentation
 
-### Fedora Docs docs (placeholder)
+The published version of this documentation is available at:
+[https://docs.fedoraproject.org/en-US/fedora-docs/](https://docs.fedoraproject.org/en-US/fedora-docs/)
 
-Under `modules/ROOT`, a placeholder for the Fedora Docs docs — intended to be moved to its own repository.
+## Contributing
 
-### Fedora Docs docs / contributing
+We welcome contributions! Whether it's fixing a typo, reporting an outdated
+page, or writing new content — every little bit helps.
 
-Under `modules/contributing`, the contributor's guide — the primary content of this repository.
+See the [Fedora Docs Contributor Guide](https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/)
+for how to get started.
 
-## Structure
+Please report **content issues** in this repository.
+For general site/publishing issues, use the
+[Fedora Docs Website repository](https://forge.fedoraproject.org/docs/docs-fp-o).
 
-```
-|-- README.md
-|-- antora.yml ....................... 1.
-|-- build.sh ......................... 2.
-|-- preview.sh ....................... 3.
-|-- site.yml ......................... 4.
-`-- modules
-    `-- ROOT ......................... 5.
-        |-- assets
-        |   `-- images ............... 6.
-        |       `-- ...
-        |-- nav.adoc ................. 7.
-        `-- pages .................... 8.
-            |-- ...
-```
-
-1. Metadata definition.
-2. A script that does a local build. Uses docker.
-3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker.
-4. A definition file for the build script.
-5. A "root module of this documentation component". Please read below for an explanation.
-6. **Images** to be used on any page.
-7. **Menu definition.** Also defines the hierarchy of all the pages.
-8. **Pages with the actual content.** They can be also organised into subdirectories if desired.
-
-## Components and Modules
-
-Antora introduces two new terms:
-
-* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Project, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity.
-* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.
-
-## Local preview
-
-This repo includes scripts to build and preview the contents of this repository.
-
-**NOTE**: Please note that if you reference pages from other repositories, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://gitlab.com/fedora/docs/-/boards) for instructions.
-
-Both scripts use docker, so please make sure you have it installed on your system. Please see below for instructions.
-
-To build and preview the site, run:
-
-```
-$ ./docsbuilder.sh
-```
-
-The result will be available at http://localhost:8080
-
-### Installing docker on Fedora
-
-```
-$ sudo dnf install docker
-$ sudo systemctl start docker && sudo systemctl enable docker
-```
+## Contact
+- **Matrix:** [#docs:fedoraproject.org](https://matrix.to/#/#docs:fedoraproject.org)
+- **Private comms:** Use our FAS emails for anything that shouldn't be public.
+- **Discussion forums:** [discussion.fedoraproject.org](https://discussion.fedoraproject.org/tag/docs-team/337)

modules/ROOT/nav.adoc

@@ -4,21 +4,26 @@
 ** xref:organizational/meetings.adoc[Docs Meetings]
 ** xref:organizational/workflow.adoc[Docs Workflow organization]
 
-* xref:contributing-docs/index.adoc[Contribute to improve and expand Docs articles]
+* xref:contributing-docs/index.adoc[Contribute to Fedora Docs]
 
 // xref:contributing-docs/contrib-existing-documentation.adoc[Contributing to existing documentation]
 ** xref:contributing-docs/contrib-new-documentation.adoc[Create a new documentation module]
 ** xref:contributing-docs/contrib-quickdocs.adoc[Contributing to Quick Docs]
 ** xref:contributing-docs/contrib-release-notes.adoc[Contributing to Release Notes]
 
-** Contribution Tools
+** How-to guides
+*** xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge]
+*** xref:contributing-docs/tools-edit-local-clone.adoc[Edit locally]
+*** xref:contributing-docs/tools-vale-linter.adoc[Check edits with Vale]
+
+** Legacy guides
 *** xref:contributing-docs/tools-gitlab-howto.adoc[HowTo for casual contributions (for GitLab-based pages)]
+//*** xref:contributing-docs/contributions-quick-repo.adoc[How to contribute to Quick Docs repo]
 *** xref:contributing-docs/tools-web-ide-ui.adoc[How to profoundly use GitLab UI for document maintenance]
 //*** xref:contributing-docs/contributions-quick-repo.adoc[How to contribute to Quick Docs repo]
 *** xref:contributing-docs/tools-file-edit-pagure.adoc[How to edit files on the Pagure Web UI]
 *** xref:contributing-docs/tools-local-authoring-env.adoc[How to create and use a local Fedora authoring environment]
 *** xref:contributing-docs/tools-localenv-preview.adoc[How to run a local preview]
-*** xref:contributing-docs/tools-vale-linter.adoc[How to check documentation style with Vale]  
 
 ** xref:contributing-docs/style-guide.adoc[The docs style guide]
 ** xref:contributing-docs/asciidoc-intro.adoc[AsciiDoc for Fedora]

modules/ROOT/pages/contributing-docs/contrib-new-documentation.adoc

@@ -17,12 +17,9 @@ Before you start following this procedure, review all the requirements listed in
 NOTE: While you can create a new repository, or use an existing one, we recommend starting from the provided template repository if you are not familiar with Antora.
 
 Create your new repository for the new documentation set, or ask someone to create one for you.
-You can host this repository anywhere but we recommend using https://gitlab.com/fedora[GitLab] where you can use Fedora groups to control write access to the repository.
-Depending on the topic, it might be preferable to host it under the https://gitlab.com/fedora/docs[Fedora Docs namespace].  
+You can host this repository anywhere but we recommend using https://forge.fedoraproject.org[Fedora Forge] where you can use Fedora groups to control write access to the repository.
 
-On GitLab, you can use `New project` > `Create from template` > `Group` and pick `Documentation Template` in the list.
-
-If you are not using GitLab, clone the https://gitlab.com/fedora/docs/templates/fedora-docs-template[template repository] manually and copy the content to your new repository.
+Simply clone the https://forge.fedoraproject.org/docs/docs-template[template repository] manually and copy the content to your new repository.
 
 .Example of a simple documentation repository structure
 ----
@@ -63,7 +60,7 @@ While you're writing, you can use the xref:contributing-docs/tools-localenv-prev
 
 Once the repository is set up, and initial content added, it is ready to be published.
 
-Documentation modules published on docs.fp-o are all listed in the https://gitlab.com/fedora/docs/docs-website/docs-fp-o/-/blob/prod/site.yml[main Antora playbook].
+Documentation modules published on docs.fp-o are all listed in the https://forge.fedoraproject.org/docs/docs-fp-o/src/branch/prod/site.yml[main Antora playbook].
 
 To add a new documentation module, you will need to add its repository to the `content.sources` list:
 
@@ -71,7 +68,7 @@ To add a new documentation module, you will need to add its repository to the `c
 ----
 content:
   sources:
-  - url: https://gitlab.com/path/to/new/repository.git
+  - url: https://forge.fedoraproject.org/path/to/new/repository.git
     branches: main <.>
     start_path: docs <.>
 ----
@@ -79,7 +76,7 @@ content:
 <.> This setting is optional. If the documentation files are stored in a subdirectory on your repository (`/docs/` for instance), you must set its relative path here, without leading or trailing slashes. If it is located at the root level, as documented on this page, you can omit this parameter.
 
 
-You can either create a Merge Request with these changes, or if you do not feel comfortable editing this file, create a ticket on the  https://gitlab.com/fedora/docs/docs-website/docs-fp-o/-/issues[Fedora Docs Website repository], and the Documentation Team will handle that part for you.
+You can either create a Pull Request with these changes, or if you do not feel comfortable editing this file, create a ticket on the https://forge.fedoraproject.org/docs/docs-fp-o/issues[Fedora Docs Website repository], and the Documentation Team will handle that part for you.
 
 
 [NOTE]

modules/ROOT/pages/contributing-docs/index.adoc

@@ -1,92 +1,158 @@
-= Contribute to Improve and Expand Docs Articles
+= Contribute to Fedora Documentation
 Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>
-:revnumber: F36 and newer
-:revdate: 2023-05-01
+:revdate: 2026-06-26
 
 :page-aliases: contributing
+:fedora-chat-url: https://matrix.to/#/#docs:fedoraproject.org?web-instance%5Belement.io%5D=chat.fedoraproject.org
+
 
 [abstract]
 ____
-This document explains how to work with the publishing system used to build the Fedora Documentation website. It will guide you through contributing to existing documentation as well as creating completely new content sets and publishing them in the English originals as well as any possible translations.
+Welcome to the Fedora Documentation Team.
+If this is your first time contributing to an open source project, Fedora Documentation is an excellent place to start.
+Whether you’re an experienced contributor or just getting started, your input is valuable and highly appreciated.
+
+This page will explain the documentation tools we use and our review process.
 ____
 
-There are many different ways to contribute to Fedora documentation. Some of them are designed to enable contributions without technical knowledge about Web Content Management Systems and about how to store and manage your contribution. The tool takes over all these issues for you. It enables authors to concentrate on the topic at hand.
+== The purpose of documentation
 
-Please check us out. If you come across a documentation page that contains an error or inaccuracy, use one of the casual contribution tools described below to improve the page. If you have any questions, please do not hesitate to contact the Docs team.
+Why do we write documentation?
+Essentially, it is to help users get tasks done.
+If a Fedora Linux user can complete a task faster, more efficiently, or with greater ease, we are achieving our goal.
+Good documentation is critical to the success of an open source project.
 
-Local authoring tools are designed to provide a powerful working environment for accomplished authors. They enable efficient work even on large complex interrelated text collections. These tools are aimed at experienced authors. 
+== What skills do I need?
 
-== How it works
+If you have some basic knowledge of Git and the AsciiDoc markup language, you are ready to go.
+If not, take a few minutes to read xref:contributing-docs/asciidoc-markup.adoc[AsciiDoc for Fedora].
+AsciiDoc and Git are easy to learn with time.
 
-Fedora documentation uses Antora to build and manage the Web site. Documentation is fairly static content, with occasional updates from time to time. This is exactly what Antora specializes in. It gathers static text documents and transforms them into a complete Web site, including navigation, links, formatting, positioning, adaptation to different output devices, etc. For more general information about the Antora publishing system, see the https://antora.org/[Antora website] and https://docs.antora.org/antora/latest/page/[Antora documentation]. 
+Okay, you are ready to start contributing to Fedora Docs - what next?
 
-As a writer, you concentrate on the content and write away.
+== First steps
 
-=== The general procedure
-
-The 4-eyes principle applies to the Fedora documentation. A different author reviews each contribution. When you complete your text or text modification, the system creates a "Pull Request" or "Merge Request" to integrate your text into the documentation body. This triggers other authors, board members or members committed to the part of the documentation body in question, to start a review and either initiates an inclusion or starts a discussion. Allow 2 to 3 days for an answer to a request.
-
-=== Some technical background
-
-Fedora uses _AsciiDoc_ to format text in a simple and efficient way. It closely follows natural writing styles in everyday notes for structuring and highlighting. In this way, you can use any editor, including almost any word processor that can edit and save AsciiDoc Text.  More about this below.
-
-The AsciiDoc text document is stored in a series of Git repositories. This is a system especially popular among software developers, but also very capable for managing text documents. Git encourages and facilitates the use of the 4-eyes principle by a "Pull (or Merge) Request Workflow". You only need to worry about the details of this workflow if you want to set up a local work environment intended for professional and frequent contributions. All other tools take care of the necessary steps in the background. 
+* Create a link:++https://accounts.fedoraproject.org/++[*Fedora Account System*] (*FAS*) account
+* Join our {fedora-chat-url}[Matrix channel] to say hello
+* Sign the xref:legal::fpca.adoc[Fedora Project Contributor Agreement].
+To sign the agreement, go to your link:++https://accounts.fedoraproject.org/++[*Fedora Account*], select "Settings" by clicking your profile image in the top right corner, and then select the "Agreements" tab. Alternatively, it can be found here, substituting your actual username: https://accounts.fedoraproject.org/user/your-username/settings/agreements/
+* Pick a https://forge.fedoraproject.org/docs/tickets/issues[docs issue], or bring your own docs issue, and get involved.
+We welcome all types of contributions, big or small.
 
 
-== Prerequisites
+=== The contributor journey
+Figure 1 provides an example overview of a contributor's journey.
 
-The only requirements for contributing documentation to Fedora Docs are:
+.Example journey
+image::int-journey.png[]
 
-* link:++https://accounts.fedoraproject.org/++[*Fedora Account System*] (*FAS*) account.
-* GitLab account
-* Must have signed https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement] from FAS. To sign, go to your Fedora Account, select "Settings" by clicking your profile image in the top right corner, and then select the "Agreements" tab. Alternatively, it can be found here, substituting your actual username: https://accounts.fedoraproject.org/user/your-username/settings/agreements/
-* Basic knowledge of *AsciiDoc* markup language (see xref:contributing-docs/asciidoc-markup.adoc[AsciiDoc for Fedora])
+== How the docs work
+
+=== Repositories
+
+Fedora documentation comprises around 60 git repositories (repos), often with a different team responsible for a given repo.
+The repos are hosted across Fedora Forge, GitLab, and GitHub.
+Previously there was also content hosted on Pagure and the Fedora wiki.
+Many of the repos have now been migrated to Forge.
+
+==== How to locate a repo
+
+To locate a page's source repo, press the edit button: icon:edit[] - located on the upper right side of the documentation page itself.
+
+==== Forks
+
+A fork is your very own, personal copy of the main upstream repo.
+All editing is done within a fork.
+This allows you to make edits and experiment with the repo without it having any effect on the main upstream repo.
+By design, most contributors will not have access to commit changes directly to the main upstream repo.
+
+==== Branches
+
+A branch is a distinct line of development within a repo.
+It provides a reference point for a specific area that you are working on, and it means that edits on one branch will not affect another.
+The majority of the upstream repos have only a single branch, the 'main' branch.
+Some repos use branches for version control, i.e. documentation that applies only to a single release version of Fedora Linux.
+
+=== Website
+Antora, a static site generator (SSG), pulls source content from the repos and generates the Fedora Documentation website, illustrated in Figure 2.
+
+.Website basics
+image::int-antora-site.png[]
+
+The reason Antora is used is because it excels at compiling from multiple source repos to generate a unified site.
+
+=== Source pages
+
+Documentation text is written in the _AsciiDoc_ markup language.
+AsciiDoc is used because it is the native language of the Antora SSG.
+It closely follows natural writing styles in everyday notes for structuring and highlighting.
+AsciiDoc can be written with almost any text editor or word processor.
+
+== About our review process
+
+Fedora documentation follows the 4-eyes policy, meaning a second person (the second set of eyes) must review and approve a documentation change/addition before it can be merged to the main site.
+We do this to maintain accuracy and consistency across our documentation.
+
+Opening a "Pull Request" (PR) initiates the review process.
+Reviewers will check for grammar, technical accuracy, style, and completeness.
+This will normally lead to the new or amended text being merged to the documentation website or a discussion on improvements.
+
+The flow of the review process is illustrated in Figure 3.
+
+.General review process
+image::int-review.png[]
+
+=== Timeline for review
+
+We aim to review and respond to PRs within seven days. If you haven't received a response within two weeks, please feel free to send a friendly reminder in our {fedora-chat-url}[Matrix channel].
+
+== Editing approaches
+
+There are two options for editing: locally on your machine, and directly on the Forge web interface.
+Both approaches have different strengths and weaknesses.
+Here is a comparison:
+
+=== Locally
+
+Editing locally allows you to:
+
+- Edit large sections or even entirely new modules
+- See a live preview of your work exactly as it will appear in the final product.
+- Work on multiple files and repos at once.
+
+While there is a lot to learn when editing locally, the power and flexibility it provides will be rewarding.
+
+Refer to the xref:contributing-docs/tools-edit-local-clone.adoc[Local workflow] guide for further information.
+
+=== Forge web interface
+
+Edits can be made directly on the Forge web interface. These are best suited for:
+
+- updating small sections
+- adding or modifying links
+- typo and grammar fixes
+
+This approach means you don't have to install any new tools on your machine.
+It also does not require use of the terminal.
+However, it has some limitations if making larger changes. It does not allow a true test preview of the pages. Images and cross references are not compiled correctly.
+
+Refer to the xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge] guide for further information.
 
 
-== The tools
+== Contribution types
 
-=== Quick way: 'Edit' button
+Some examples of contributions include:
 
-- Make changes to a single file for minor fixes directly from web UI of Git forge.
-- Write access to upstream repo required.
-- Use it as an exception (without review process), rather than a recommended option.
-   
-=== Easy way: Web IDE of Git forge
+- correcting small errors
+- adding, removing, and modifying links
+- revising existing pages
+- writing new pages
+- translation
+- general ideas to improve the docs
 
-- Make changes to multiple files directly from web UI of Git forge.
-- No need to install anything in local computer or run Git commands in terminal.
-- Pull Requests for review process (Merge Requests in GitLab)
-- You do not need special permissions or write access to the original project.
-   
-=== Flexible and advanced way: Create a local writing environment
+== Larger contributions
 
-- Work with multiple files and repos offline at your pace using your choice of text editor and terminal.
-- You can build and render the pages locally to test your changes using Podman container.
+The smaller a PR, the easier and quicker it is to review.
+If you would like to complete a major revision of a page, or write an entirely new page or section, reach out to us on the Fedora Documentation {fedora-chat-url}[Matrix channel].
+This helps to ensure your time is wisely spent and allows others to weigh in on the direction that we take together as a project.
 
-== Typical ways to contribute
-
-One can distinguish several typical types of contribution to Fedora documentation, for which the available tools are suitable in different ways.
-
-There are many ways for various types of contribution. For example, typo fixes, adding short information or a link, update an article, write a new article.
-
-=== Update an existing documentation page 
-
-This task involves minor changes. For example, typo fixes, adding short information or a link, or a correction to the text. This type is especially necessary whenever the documentation needs to be updated for a new software version.
-
-The _File Edit button_ are convenient for this purpose. 
-
-=== Extend an existing documentation domain
-   
-This task involves adding one or more new chapter(s) or section(s) with several chapters. For example, adding another container technique to the documentation of containerization. 
-
-The _Web IDE_ is a convenient tool for this purpose. A local writing environment is useable as well, but may involve too much overhead if you want to contribute to just one document.
-
-It is highly recommended to present the plan on one of the Docs communication channels before starting. You may get suggestions and tips on content, but also on editing. For example, file structure and naming conventions.
-
-=== Introduce a new documentation area
-
-This task involves a new extensive subject area, such as new software or a new administration tool. For example, inclusion of several sections and chapters and the creation of a new, separate repository.
-
-For this type, setting up a local writing environment is useful and worthwhile.
-
-In any case, a prior discussion with the Docs team is necessary, if only to create the technical prerequisites.

modules/ROOT/pages/contributing-docs/tools-edit-local-clone.adoc

@@ -0,0 +1,224 @@
+= Edit Documentation Locally
+:revdate: 2026-04-01
+:page-pagination:
+Jocelyn Gould (korora) and Eli Ridge (egret)
+
+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.
+
+[IMPORTANT]
+====
+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 xref:contributing-docs/index.adoc[Contribute to Fedora docs] page.
+
+//above links to the current live page not the update draft.
+
+== Prerequisites
+
+* xref:contributing-docs/index.adoc#_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:
++
+[source,console]
+----
+$ 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.
++
+[source,console]
+----
+$ 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:
++
+image::fork-button.png[]
++
+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 xref:forge-documentation::using_http_auth.adoc[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.
++
+[source,console]
+----
+$ git remote add upstream https://forge.fedoraproject.org/docs/<name-of-upstream-repo>.git
+----
++
+Verify it with:
++
+[source,console]
+----
+$ 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:
++
+[source,console]
+----
+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)
+----
++
+[NOTE]
+====
+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:
++
+[source,console]
+----
+$ git checkout -b <branch-name-you-choose>
+----
+
+See xref:contributing-docs/tools-edit-local-clone.adoc#_branching[here] for further information on branching.
+
+You are now ready to start writing.
+Consider making use of the xref:contributing-docs/style-guide.adoc[Fedora style guide] as well as the xref:contributing-docs/tools-vale-linter.adoc[Vale] tool to assist your editing.
+
+== Edit the AsciiDoc code
+
+You can open and edit AsciiDoc files with any text editor.
+
+[NOTE]
+====
+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.
+
+. In the terminal, navigate to your project folder.
+Run the _docsbuilder_ script by entering this command:
++
+[source,console]
+----
+$ ./docsbuilder.sh
+----
++
+A successful output will resemble this:
++
+[source,console]
+----
+...
+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/) ...
+----
+
+. In a browser, visit http://localhost:8080.
+
+. To update the preview after further edits:
+.. Ensure the script is at rest - the terminal window activity should have stopped and the last sentence read `Watching current directory...`.
+.. Save the .adoc file you have been editing and observe the script complete again.
+.. Refresh the browser window.
+
+[NOTE]
+====
+On MacOS, the _docsbuilder_ script uses Docker instead of Podman.
+You can install Docker from the official https://www.docker.com/[Docker Website].
+====
+
+See xref:contributing-docs/tools-edit-local-clone.adoc#_the_docsbuilder_script_and_podman[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:
++
+[source,console]
+----
+$ 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:
++
+[source,console]
+----
+$ git add <path-to-changed-file>
+----
+
+3. Commit with a message:
++
+[source,console]
+----
+$ git commit -m <meaningful-name-reflecting-what-you-changed>
+----
+
+4. Push your changes:
++
+[source,console]
+----
+$ 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.

modules/ROOT/pages/contributing-docs/tools-file-edit-forge.adoc

@@ -0,0 +1,52 @@
+= Edit a Page Using the Forge Web Interface
+Eli R
+:revnumber: F43 and newer
+:revdate: 2026-04-04
+
+This section will guide you through editing a documentation (docs) page using the Fedora Forge web interface.
+
+Use this method for small changes, such as fixing typos or other simple edits that affect a single page.
+
+== Preparation
+
+* Complete the contributor https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/#_prerequisites[*prerequisites*].
+
+== Edit via the Forge web interface
+
+Every documentation page has an icon:edit[] *Edit this page* button in the top right corner.
+Use this to locate the page's source repository on Fedora Forge.
+
+Starting from the docs.fedoraproject.org page that you intend to edit:
+
+1. Click the icon:edit[] *Edit* button in the top right corner to navigate to the source page.
+
+2. If you are not already signed in, do so with your FAS account.
+
+3. Click the *Fork* button (normally top right). If prompted, enter the details to create your new fork. The default values are suitable in most cases.
++
+IMPORTANT: If you receive a warning that the branch is behind in commits, click the _Sync_ button so that it matches the upstream repo.
+
+4. Manually navigate the folder structure to return to the source page you intend to edit (normally in modules/ROOT/pages/).
+
+5. Click the icon:pen[] *Edit* button, located on the right side above the file contents, and make your changes directly to the AsciiDoc code.
+
+6. Use the icon:eye[] *Preview* button, located on the left side above the edit field, to see how the document will look. Keep in mind that some AsciiDoc elements may not render accurately in the preview.
+
+7. Once you are happy with the edit, scroll to the bottom of the page, and optionally add a message describing the nature of the edit.
+
+8. Check "Create a *new branch* for this commit and start a pull request". Optionally, rename the new branch.
+
+9. Click *propose file change*, which brings you to the *New pull request* page
+
+10. Use the first drop-down selector, *merge into*, to select the upstream repo. This is normally the *main* branch, but check with the repository maintainers if in doubt.
+
+11. Ensure the *pull from* selector is set to your personal fork, on the newly created branch from step 8.
+
+12. Click *New pull request*.
+
+13. Carry out any final checks, then click *Create pull request*.
+
+[NOTE]
+====
+It may take a number of days before your pull request is reviewed. If you have not received a response within five days of opening the PR, consider using Matrix to reach out to the team that is responsible for that repo.
+====

modules/ROOT/pages/contributing-docs/tools-file-edit-pagure.adoc

@@ -3,7 +3,7 @@ Hanku Lee
 :revnumber: F33 and newer
 :revdate: 2023-04-18
 
-IMPORTANT: Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge]. 
+IMPORTANT: Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge]. See the updated xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge] guide.
 
 This section describes how to contribute to existing documentation - that is, documentation that already has been published on the website.
 Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:index.adoc[Prerequisites].

modules/ROOT/pages/contributing-docs/tools-gitlab-howto.adoc

@@ -3,7 +3,7 @@ Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>
 :revdate: 2023-26-06
 :page-pagination:
 
-IMPORTANT: Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge]. 
+IMPORTANT: Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge]. See the updated xref:contributing-docs/tools-file-edit-forge.adoc[Edit a single page in Forge] guide.
 
 [abstract]
 To make changes in Docs page hosted on GitLab, you have a built-in web editor that makes your first contribution easier than ever. Start editing documentation on GitLab Web IDE that you can launch in one click. You do not need special permissions or write access to the original project.

modules/ROOT/pages/contributing-docs/tools-local-authoring-env.adoc

@@ -3,6 +3,12 @@ Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs-team>
 :revdate: 2024-08-30
 :page-pagination:
 
+[IMPORTANT]
+====
+Many of the repositories have now been migrated to https://forge.fedoraproject.org[Fedora Forge].
+See the updated xref:contributing-docs/tools-edit-local-clone.adoc[Edit from a local clone] guide.
+====
+
 [abstract]
 In a local environment, you can create or edit your documents offline. You use a local git repository that contains a complete set of documents and tools to edit. After editing is complete, preview them in a local build of Docs pages. It is by far the most flexible way of working with Docs repositories, enabled by the extensive adaptation to individual work routines and work equipment. A local writing environment allows full access to all the resources you routinely use on your workstation and is therefore perfectly adaptable to your style of working. It is particularly suitable for the creation of a completely new set of documentation on a topic or for revision of an existing set of documentation. This article takes an example of the Fedora project repositories in GitLab, but the overall process can be translated for Pagure and GitHub projects.
 

modules/ROOT/pages/organizational/meetings.adoc

@@ -1,6 +1,6 @@
 = Communication and Meetings
 
-Fedora Docs currently holds weekly meetings on IRC/Telegram/Matrix.
+Fedora Docs currently holds weekly meetings on Matrix in `#meeting:fedoraproject.org` (Fedora Meeting) room.
 See the link:++https://calendar.fedoraproject.org//docs/++[docs calendar] for current meeting times,
 and xref:index.adoc#find-docs[the main page] for information about joining.
 
@@ -8,8 +8,8 @@ This page describes the structure in the meetings.
 
 == Pre-meeting
 
-Items to be discussed in meetings should be tagged with the link:++https://gitlab.com/groups/fedora/docs/-/issues?label_name=Meeting++[Meeting] tag.
-While preparing the agenda, review the https://gitlab.com/groups/fedora/docs/-/boards[issue board] for items that should be tagged for the meeting.
+Items to be discussed in meetings should be tagged with the link:https://forge.fedoraproject.org/docs/tickets/issues?labels=3655[Meeting] tag.
+While preparing the agenda, review the https://forge.fedoraproject.org/docs/tickets/projects/407[issue board] for items that should be tagged for the meeting.
 At least a day or two prior to the meeting, the chair should post a thread with the agenda
 on the link:++https://discussion.fedoraproject.org/tag/docs-team++[forums].
 Team members may suggest additional topics in these threads.
@@ -19,61 +19,59 @@ Team members may suggest additional topics in these threads.
 Follow this general script for the meeting.
 
 ```
-#startmeeting docs
+!startmeeting docs
 
-#topic Roll call
+!topic Roll call
 ```
 
 Wait 3–5 minutes to see who is present.
 
-TIP: In case you need to step away or get disconnected, add other chairs (e.g. xref:index.adoc#_the_board[board members]) with: #chair <NICK>
+TIP: In case you need to step away or get disconnected, add other chairs (e.g. xref:index.adoc#_the_board[board members]) with: !chair <NICK>
 
 List the agenda for the meeting:
 
 ```
-#topic Agenda
-#info Announcements
-#info Review action items
-#info <topic 1>
-#info <topic 2>
-#info …
+!topic Agenda
+- Announcements
+- Review action items
+- <topic 1>
+- <topic 2>
+- Open Floor
 ```
 
 Start with any important announcements.
-(e.g. Release Notes that need to be written, upcoming deadlines, a link to the https://gitlab.com/groups/fedora/docs/-/boards[issue board], etc.)
+(e.g. Release Notes that need to be written, upcoming deadlines, a link to the https://forge.fedoraproject.org/docs/tickets/projects/407[issue board], etc.)
 
-Next, review action items from https://meetbot.fedoraproject.org/sresults/?group_id=docs&type=team[previous meetings].
+Next, review action items from https://meetbot.fedoraproject.org/[previous meetings].
 Get updates when there are updates to get.
 If an action item is still open,
-use the `#action` command to assign it again.
+use the `!action` command to assign it again.
 This keeps chairs from having to search many previous meetings.
 
 ```
-#topic Previous action items
-#info <nick> was to <action>
+!topic Previous action items
+!info <nick> was to <action>
 ```
 
 Proceed through the other agenda topics.
-Use `#topic` to change the topic.
-Make frequent use of `#info` and `#link` commands to add context to the minutes.
+Use `!topic` to change the topic.
+Make frequent use of `!info` and `!link` commands to add context to the minutes.
 If someone needs to act,
-use `#action <nick> to <action>` to note it in the minutes.
-Note agreements with the `#agreed` command.
+use `!action <nick> to <action>` to note it in the minutes.
+Note agreements with the `!agreed` command.
+To indicate you're present type `!hi`.
 
 TIP: Most of the time,
-something that is #agreed should be recorded elsewhere after the meeting.
+something that is !agreed should be recorded elsewhere after the meeting.
 For example,
 in the resolution of a ticket
 or as a new policy/procedure in the documentation.
 
-NOTE: Should we add a regular content-related topic?
-https://discussion.fedoraproject.org/t/fedora-and-centos-docs-revitalization/36353/7[Peter Boy suggested this].
-
 If time permits,
 open the floor for other discussion.
 
 ```
-#topic Open floor
+!topic Open floor
 ```
 
 CAUTION: Do not make decisions in the open floor section.
@@ -85,7 +83,7 @@ In most cases, decisions should happen asynchronously.
 When time is up or there are no more topics to discuss, end the meeting.
 
 ```
-#endmeeting
+!endmeeting
 ```
 
 == Post-meeting
@@ -93,3 +91,5 @@ When time is up or there are no more topics to discuss, end the meeting.
 Paste the links to the minutes and logs in the Discussion thread you used for the agenda.
 Note any important outcomes.
 Update tickets or discussion threads with actions, agreements, etc.
+
+Past meeting minutes are available through https://meetbot.fedoraproject.org/.

preview.pid

@@ -1 +0,0 @@
-10709