change-requests2

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

@@ -1,20 +1,21 @@
-= Edit Documentation Using a Local Workflow
+= 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.
+[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.
+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.
 
@@ -40,8 +41,8 @@ The example uses the name "fedora-docs" but you can use any name.
 +
 [source,console]
 ----
-mkdir ~/fedora-docs
-cd    ~/fedora-docs
+$ mkdir ~/fedora-docs
+$ cd    ~/fedora-docs
 ----
 
 
@@ -59,21 +60,23 @@ Follow the xref:forge-documentation::using_http_auth.adoc[How to clone a Forge r
 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
+$ git remote add upstream https://forge.fedoraproject.org/docs/<name-of-upstream-repo>.git
 ----
 +
 Verify it with:
 +
 [source,console]
 ----
-git remote -v
+$ 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 should resemble this:
+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)
@@ -81,37 +84,33 @@ 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.
+[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>
+$ git checkout -b <branch-name-you-choose>
 ----
 
-//See here for an explanation of branches and why it is best practice to create a working branch/s.
-
-****
-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.
-****
+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 with a text editor
+== 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:
 
@@ -129,12 +128,14 @@ The _docsbuilder_ script uses Podman to build a preview of your docs pages in an
 . In the terminal, navigate to your project folder.
 Run the _docsbuilder_ script by entering this command:
 +
+[source,console]
 ----
-./docsbuilder.sh
+$ ./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.
@@ -148,8 +149,11 @@ Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...
 .. 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.
+[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.
 
@@ -157,29 +161,32 @@ See xref:contributing-docs/tools-edit-local-clone.adoc#_the_docsbuilder_script_a
 
 1. Determine the files that have been changed and added to the branch you are working on:
 +
+[source,console]
 ----
-git status
+$ 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>
+$ git add <path-to-changed-file>
 ----
 
 3. Commit with a message:
 +
+[source,console]
 ----
-git commit -m <meaningful-name-reflecting-what-you-changed>
+$ git commit -m <meaningful-name-reflecting-what-you-changed>
 ----
 
 4. Push your changes:
 +
+[source,console]
 ----
-git push origin <branch-name>
+$ git push origin <branch-name>
 ----
 
 You are now ready to open a pull request (PR).
@@ -196,7 +203,15 @@ You are now ready to open a pull request (PR).
 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.
 
-== The docsbuilder script and Podman
+== 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.