docs/team-docs
19
4
Fork 9
Code Issues 6 Pull requests 1 Projects Activity Actions

local-workflow-update #58

Merged
pbokoc merged 10 commits from egret/team-docs:local-docscontrib into main 2026-05-30 10:52:13 +00:00
Conversation 13 Commits 10 Files changed 4 +166 -1
3 changed files with 166 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit fbe29fcef8 - Show all commits

edit-local-draft

Prev Next
Eli Ridge 2026-04-23 00:34:49 +12:00
commit fbe29fcef8

2
modules/ROOT/nav.adoc
View file

@ -20,7 +20,7 @@
*** 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/tools-file-edit-forge.adoc[Edit a single page in Forge]
*** xref:contributing-docs/tools-edit-local-clone.adoc[Edit locally]
** xref:contributing-docs/style-guide.adoc[The docs style guide]
** xref:contributing-docs/asciidoc-intro.adoc[AsciiDoc for Fedora]

163
modules/ROOT/pages/contributing-docs/tools-edit-local-clone.adoc Normal file
View file

@ -0,0 +1,163 @@
= Edit Documentation Using a Local Workflow
egret marked this conversation as resolved
pbokoc commented 2026-05-29 12:44:01 +00:00
Copy link

The title is really clunky. How about "Edit documentation locally"?

The title is really clunky. How about "Edit documentation locally"?
:revdate: 2026-04-01
:page-pagination:
Jocelyn G and Eli R
This guide will show you how to set up a documentation (docs) editing environment with a local clone.
[EXPLANATION]
egret marked this conversation as resolved
pbokoc commented 2026-05-29 12:46:35 +00:00
Copy link

The **** creates this weird box in the rendered page that we don't use anywhere else. I'd suggest leaving this as a standard paragraph, or a [NOTE] in the following format:

[NOTE]
====
text
====

This happens multiple times throughout the PR and I don't want to open a new note for each occurence. Please go through both the adoc files, search for ****, and change them all.

The `****` creates this weird box in the rendered page that we don't use anywhere else. I'd suggest leaving this as a standard paragraph, or a `[NOTE]` in the following format: ~~~ [NOTE] ==== text ==== ~~~ This happens multiple times throughout the PR and I don't want to open a new note for each occurence. Please go through both the adoc files, search for `****`, and change them all.
====
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.
egret marked this conversation as resolved
pbokoc commented 2026-05-29 12:47:32 +00:00
Copy link

This should be formatted as

[IMPORTANT]
====
text
====

It renders the same but this is the convention we usually go with.

This happens multiple times throughout the PR and I don't want to open a new note for each occurence. Please go through the whole file, search for NOTE and IMPORTANT, and change them all to blocks like indicated above.

This should be formatted as ~~~ [IMPORTANT] ==== text ==== ~~~ It renders the same but this is the convention we usually go with. This happens multiple times throughout the PR and I don't want to open a new note for each occurence. Please go through the whole file, search for `NOTE` and `IMPORTANT`, and change them all to blocks like indicated above.
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.
egret marked this conversation as resolved
pbokoc commented 2026-05-29 12:44:57 +00:00
Copy link

No spaces between the link URL and [link text]

No spaces between the link URL and `[link text]`
For explanation and references on the Fedora docs tooling, please visit the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/[Contribute to Fedora docs] page.
//above links to the live page not the draft of the updated one
== Prerequisites
* https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/#_prerequisites[*First steps*] section completed.
* *Git* installed.
* *Text editor* of choice installed.
It is beneficial but not essential if your text editor has integrated file navigation, 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,]
----
mkdir ~/fedora-docs
egret marked this conversation as resolved
pbokoc commented 2026-05-29 12:49:28 +00:00
Copy link

Add the $ prompt to commands to differentiate between them and output (if there is any).

This applies to the whole PR, there's a bunch of cases.

Add the `$` prompt to commands to differentiate between them and output (if there is any). This applies to the whole PR, there's a bunch of cases.
cd ~/fedora-docs
----
2. Use the Forge web interface to fork the repo you intend to edit.
2. Configure your Forge access token and clone your remote fork to your machine.
Follow the https://docs.fedoraproject.org/en-US/forge-documentation/using_http_auth/[How to clone a Forge repo using the HTTPS] guide to complete this.
3. Configure the upstream repo in your local clone.
You will need this to fetch updates from the upstream main docs repo.
+
----
egret marked this conversation as resolved
pbokoc commented 2026-05-29 12:51:18 +00:00
Copy link

Add [source,console] to the line above to make sure it renders the same as other examples.

Applies to the whole PR - please go through the whole thing and add it everywhere it's missing, I don't want to copypaste this everywhere.

Add `[source,console]` to the line above to make sure it renders the same as other examples. Applies to the whole PR - please go through the whole thing and add it everywhere it's missing, I don't want to copypaste this everywhere.
git remote add upstream https://forge.fedoraproject.org/docs/team-docs.git
----
+
egret marked this conversation as resolved
jflory7 commented 2026-05-28 14:25:53 +00:00
Copy link

https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
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 return should 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)
----
+
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 indeed choose different names to represent the two different repos if you choose to.
5. Create a working branch:
+
----
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.
If making large changes, consider making a new branch for each page, so the reviews can happen in stages.
You are now ready to start writing.
Consider making use of the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/[Fedora style guide] as well as the https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-vale-linter/[Vale] tool to assist your editing.
== Edit the AsciiDoc code with a text editor
Configure your text editor or IDE of choice with the following three viewing windows:
* 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 for convenience.
== Preview your work
. In the terminal, navigate to your project folder. Type and enter this command:
+
----
./docsbuilder.sh
----
[EXPLANATION]
====
The ./docsbuilder 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.
====
. 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 completes again.
.. Refresh the browser window.
== Pushing your changes to your remote fork in Forge
1. Add the changes to your local git staging ground
+
----
git add .
----
2. Commit with a message
+
----
git commit -m <meaningful-name-reflecting-what-you-changed>
----
3. Push your changes
+
----
git push origin <branch-name>
----
You are now ready to open a pull request
== Checklist
* [ ] Checked for spelling and grammatical errors
* [ ] Metadata and author tags entered.
* [ ] Tested and previewed using the ./docsbuilder script.
== Opening a Pull Request
On the Forge web interface, navigate to your fork's repo and the branch you have been working.
Use the click button to open the Pull request.

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

@ -3,6 +3,8 @@ 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-file-edit-forge.adoc[Edit from a local clone] guide.
egret marked this conversation as resolved
pbokoc commented 2026-05-29 21:30:22 +00:00
Copy link

Missed this one :P

Missed this one :P
[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.