From 0f5631b1089ebcb9d0774bbd60596d290fe0de2e Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Tue, 10 Feb 2026 17:05:56 +0900 Subject: [PATCH 01/14] Add contributing guide for Rocky Linux documentation Adds a comprehensive contributing guide at docs/guides/contribute/contributing.md covering environment setup, validation tools, formatting guidelines, and PR workflow for Rocky Linux 10, 9, 8, macOS, and Windows contributors. Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/contributing.md | 1404 ++++++++++++++++++++++++ 1 file changed, 1404 insertions(+) create mode 100644 docs/guides/contribute/contributing.md diff --git a/docs/guides/contribute/contributing.md b/docs/guides/contribute/contributing.md new file mode 100644 index 0000000000..5a775f26c8 --- /dev/null +++ b/docs/guides/contribute/contributing.md @@ -0,0 +1,1404 @@ +--- +title: Contributing to the Rocky Linux Documentation +author: Howard Van Der Wal +tags: + - contributing + - documentation + - guide +--- + +# Contributing to the Rocky Linux Documentation + +## AI Usage Disclosure + +This document was created with the assistance of AI. All content has been reviewed, tested, and verified by a human author. The author takes full responsibility for the accuracy and correctness of this document. + +## Welcome + +Thank you for your interest in contributing to the Rocky Linux documentation. This guide walks you through everything you need to create, edit, and submit documentation that meets our standards. + +## Table of Contents + +* [Quick Start](#quick-start) +* [Prerequisites](#prerequisites) +* [Fork and Clone the Repository](#fork-and-clone-the-repository) +* [Setting Up Your Environment](#setting-up-your-environment) + * [Alternative Tooling](#alternative-tooling) + * [Local Editors](#local-editors) + * [Rocky Linux 10 Setup](#rocky-linux-10-setup) + * [Rocky Linux 9 Setup](#rocky-linux-9-setup) + * [Rocky Linux 8 Setup](#rocky-linux-8-setup) + * [macOS Sequoia Setup](#macos-sequoia-setup) + * [Windows 11 Setup](#windows-11-setup) + * [Install Pre-commit Hooks (Required)](#install-pre-commit-hooks-required) +* [Creating New Documentation](#creating-new-documentation) + * [Document Naming](#document-naming) + * [Document Location](#document-location) + * [Document Structure](#document-structure) + * [Example Guides](#example-guides) + * [AI Usage](#ai-usage) +* [Formatting Guidelines](#formatting-guidelines) + * [Style Guide](#style-guide) + * [Markdown Formatting](#markdown-formatting) + * [Code Blocks](#code-blocks) +* [Validation Checks](#validation-checks) + * [Running Checks Manually](#running-checks-manually) + * [Rocky Docs Contribution Guidelines Validation](#rocky-docs-contribution-guidelines-validation) + * [Adding Words to the Dictionary](#adding-words-to-the-dictionary) +* [Submitting a Pull Request](#submitting-a-pull-request) +* [Getting Help](#getting-help) +* [Additional Resources](#additional-resources) +* [License](#license) + +## Quick Start + +1. Fork the [Rocky Linux Documentation repository](https://github.com/rocky-linux/documentation) +2. Clone your fork locally +3. Set up pre-commit hooks (required) +4. Create or edit documentation +5. Run validation checks +6. Submit a pull request + +## Prerequisites + +Before contributing, you need: + +- A [GitHub account](https://github.com/signup) +- [Git](https://git-scm.com/downloads) installed on your machine +- [Python 3.8+](https://www.python.org/downloads/) for spell checking +- [Node.js](https://nodejs.org/) for markdown linting +- A text editor (see [Local Editors](#local-editors) below) + +## Fork and Clone the Repository + +1. Navigate to the [Rocky Linux documentation repository](https://github.com/rocky-linux/documentation) +2. Click the **Fork** button in the upper right corner +3. Clone your fork to your local machine: + +```bash +git clone https://github.com/YOUR_USERNAME/documentation.git +cd documentation +``` + +4. Add the upstream repository as a remote: + +```bash +git remote add upstream https://github.com/rocky-linux/documentation.git +``` + +## Setting Up Your Environment + +### Alternative Tooling + +The setup instructions in this section describe one approach to documentation validation using pre-commit hooks and command-line tools. There are other methods available to check your markdown documents, before submitting them as a PR. + +If you already use a terminal-based editor (Neovim, Emacs, Helix, etc.) with integrated linting tools, you can continue using your existing workflow. Tools like: + +- [markdownlint](https://github.com/DavidAnson/markdownlint) or [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) - Available as editor plugins for real-time markdown linting +- [vale](https://github.com/errata-ai/vale) - Prose linter that can enforce style guide rules +- [harper-ls](https://github.com/Automattic/harper) - Grammar checker with LSP support +- [ltex-ls](https://github.com/valentjn/ltex-ls) - LanguageTool-based grammar and spell checking via LSP + +These tools provide the same validation capabilities and can be configured to match the Rocky Linux documentation standards. The key requirement is that your contributions pass the automated CI checks when you submit a pull request, regardless of which tools you use locally. + +### Local Editors + +Choose a markdown editor that suits your workflow: + +#### Graphical Editors + +- [ReText](https://github.com/retext-project/retext) - Free, cross-platform, open source +- [Zettlr](https://www.zettlr.com/) - Free, cross-platform, open source +- [MarkText](https://github.com/marktext/marktext) - Free, cross-platform, open source +- [Remarkable](https://remarkableapp.github.io/) - Linux and Windows, open source +- [VS Code](https://code.visualstudio.com/) - Partially open source, by Microsoft. Recommended extensions: Git Graph, Markdown All in One, Markdown Preview Enhanced, markdownlint + +#### Terminal Editors + +- [NvChad](https://nvchad.com/) - For Neovim users. See our [NvChad setup guide](https://docs.rockylinux.org/books/nvchad/) +- [Doom Emacs](https://github.com/doomemacs/doomemacs) - For Emacs users. Enable the `markdown` module in your config + +Terminal editors can integrate the same validation tools used by the pre-commit hooks directly into your editing workflow: + +- [markdownlint](https://github.com/DavidAnson/markdownlint) +- [vale](https://github.com/errata-ai/vale) +- [harper-ls](https://github.com/Automattic/harper) +- [ltex-ls](https://github.com/valentjn/ltex-ls) + +### Rocky Linux 10 Setup + +If you are running Rocky Linux 10, follow these steps to set up a complete documentation validation environment. This installs all required tools and enables you to run the same checks that the Documentation Team uses to validate pull requests. + +#### Step 1: Install System Dependencies + +```bash +# Note: npm is bundled with nodejs in Rocky Linux 10 +sudo dnf install -y git python3-pip hunspell hunspell-en-US nodejs +``` + +#### Step 2: Install Python Packages + +```bash +pip install pre-commit pyspelling +``` + +#### Step 3: Install Node.js Packages + +```bash +sudo npm install -g markdownlint-cli +``` + +#### Step 4: Install Lychee Link Checker + +Lychee is not available in the Rocky Linux repositories, so install the binary directly: + +```bash +cd /tmp +curl -sLO https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz +tar xzf lychee-x86_64-unknown-linux-gnu.tar.gz +sudo mv lychee /usr/local/bin/ +sudo chmod +x /usr/local/bin/lychee +rm -f lychee-x86_64-unknown-linux-gnu.tar.gz +``` + +Verify the installation: + +```bash +lychee --version +``` + +#### Step 5: Clone your Forked Repository and Configure it + +```bash +git clone https://github.com/YOUR_USERNAME/documentation.git +cd documentation +``` + +If you have already cloned the repository, ensure it is up to date: + +```bash +cd documentation +git pull origin main +``` + +#### Step 6: Verify Pyspelling Configuration + +The repository includes a `.pyspelling.yml` configured for Hunspell, which is the default spell checker on Rocky Linux 10. No additional configuration is needed. Verify that Hunspell is installed: + +```bash +rpm -q hunspell hunspell-en-US +``` + +If not installed: + +```bash +sudo dnf install -y hunspell hunspell-en-US +``` + +#### Step 7: Install Pre-commit Hooks + +```bash +pre-commit install +``` + +#### Step 8: Verify Your Setup + +Run all validation checks to confirm everything is working: + +```bash +pre-commit run --all-files +``` + +#### Expected Behavior on First Run + +When running `pre-commit run --all-files` for the first time, you may see errors from existing repository files. This is expected behavior: + +| Hook | Expected Result | Notes | +|------|-----------------|-------| +| trailing-whitespace | May auto-fix files | Changes are staged automatically | +| end-of-file-fixer | May auto-fix files | Changes are staged automatically | +| check-yaml | Pass | MkDocs config files are excluded | +| check-added-large-files | Pass | | +| markdownlint | May show errors | | +| pyspelling | Pass (with Hunspell config) | Requires Step 6 configuration | +| lychee | Pass | Some timeouts are normal | + +**Important**: The markdownlint errors you see are in existing repository documentation files, not files you created. When contributing, you only need to ensure your own files pass validation. + +#### Step 9: Validate Your Document + +Before submitting your documentation, validate your specific file to ensure it passes all checks: + +```bash +# Spell check +pyspelling -n Markdown -S "docs/guides/your-document.md" + +# Markdown lint +markdownlint "docs/guides/your-document.md" + +# Link check +lychee "docs/guides/your-document.md" --no-progress +``` + +Example output for a passing spell check: + +```text +pyspelling -n Markdown -S "docs/guides/hpc/slurm-rocky.md" +Spelling check passed :) +``` + +Example output for a failing markdown lint check: + +```text +markdownlint docs/guides/automation/kickstart-rocky-broken.md +docs/guides/automation/kickstart-rocky-broken.md:1 error MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "---"] +docs/guides/automation/kickstart-rocky-broken.md:162 error MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3] +``` + +Example output for a passing link check: + +```text +lychee docs/guides/hpc/slurm-rocky.md --no-progress +🔍 8 Total (in 0s) ✅ 8 OK 🚫 0 Errors +``` + +### Rocky Linux 9 Setup + +If you are running Rocky Linux 9, follow these steps to set up a complete documentation validation environment. Rocky Linux 9 uses Hunspell for spell checking (aspell is not available in EPEL for Rocky Linux 9). + +#### Step 1: Install System Dependencies + +```bash +sudo dnf install -y git python3-pip hunspell hunspell-en-US nodejs npm +``` + +#### Step 2: Install Python Packages + +```bash +pip install --user pre-commit pyspelling +``` + +#### Step 3: Install Node.js Packages + +```bash +sudo npm install -g markdownlint-cli +``` + +#### Step 4: Install Lychee Link Checker + +Lychee is not available in the Rocky Linux repositories, so install the binary directly: + +```bash +cd /tmp +curl -sLO https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz +tar xzf lychee-x86_64-unknown-linux-gnu.tar.gz +sudo mv lychee /usr/local/bin/ +sudo chmod +x /usr/local/bin/lychee +rm -f lychee-x86_64-unknown-linux-gnu.tar.gz +``` + +Verify the installation: + +```bash +lychee --version +``` + +#### Step 5: Clone your Forked Repository and Configure it + +```bash +git clone https://github.com/YOUR_USERNAME/documentation.git +cd documentation +``` + +#### Step 6: Verify Pyspelling Configuration + +The repository includes a `.pyspelling.yml` configured for Hunspell, which is the default spell checker on Rocky Linux 9. No additional configuration is needed. Verify that Hunspell is installed: + +```bash +rpm -q hunspell hunspell-en-US +``` + +If not installed: + +```bash +sudo dnf install -y hunspell hunspell-en-US +``` + +#### Step 7: Install Pre-commit Hooks + +```bash +~/.local/bin/pre-commit install +``` + +**Note**: When using `pip install --user`, the `pre-commit` binary is installed to `~/.local/bin/`. You can either use the full path or add `~/.local/bin` to your PATH: + +```bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +#### Step 8: Verify Your Setup + +Run all validation checks to confirm everything is working: + +```bash +~/.local/bin/pre-commit run --all-files +``` + +#### Step 9: Validate Your Document + +Before submitting your documentation, validate your specific file to ensure it passes all checks: + +```bash +# Spell check +pyspelling -n Markdown -S "docs/guides/your-document.md" + +# Markdown lint +markdownlint "docs/guides/your-document.md" + +# Link check +lychee "docs/guides/your-document.md" --no-progress +``` + +### Rocky Linux 8 Setup + +If you are running Rocky Linux 8, follow these steps to set up a complete documentation validation environment. Rocky Linux 8 uses Aspell for spell checking (available from base repositories). + +#### Step 1: Install System Dependencies + +Rocky Linux 8 uses Python 3.9 and Node.js module streams: + +```bash +# Install Python 3.9 and other dependencies +sudo dnf install -y git python39-pip python39 aspell aspell-en + +# Enable Node.js 18 module stream +sudo dnf module enable -y nodejs:18 + +# Install Node.js +sudo dnf install -y nodejs +``` + +#### Step 2: Install Python Packages + +Use Python 3.9's pip: + +```bash +pip3.9 install --user pre-commit pyspelling +``` + +#### Step 3: Install Node.js Packages + +```bash +sudo npm install -g markdownlint-cli +``` + +#### Step 4: Install Lychee Link Checker + +Lychee is not available in the Rocky Linux repositories, so install the binary directly: + +```bash +cd /tmp +curl -sLO https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz +tar xzf lychee-x86_64-unknown-linux-gnu.tar.gz +sudo mv lychee /usr/local/bin/ +sudo chmod +x /usr/local/bin/lychee +rm -f lychee-x86_64-unknown-linux-gnu.tar.gz +``` + +Verify the installation: + +```bash +lychee --version +``` + +#### Step 5: Clone your Forked Repository and Configure it + +```bash +git clone https://github.com/YOUR_USERNAME/documentation.git +cd documentation +``` + +#### Step 6: Configure Pyspelling for Aspell + +The repository `.pyspelling.yml` is configured for Hunspell by default. Rocky Linux 8 uses Aspell instead, so you need to create a local override. Create a `.pyspelling.yml` file in the repository root: + +```bash +cat > .pyspelling.yml << 'EOF' +spellchecker: aspell +matrix: + - name: Markdown + sources: + # Process English files only - exclude translations + - 'docs/**/*.md|!docs/**/*.{af,de,en,es,fr,hi,id,it,ja,ko,pl,pt,pt-BR,sv,tr,uk,zh}.md' + expect_match: false + aspell: + lang: en + d: en_US + dictionary: + wordlists: + - .wordlist.txt + output: build/spelling-wordlist.dic + pipeline: + - pyspelling.filters.markdown: + - pyspelling.filters.html: + comments: true + ignores: + - code + - pre + - kbd + - pyspelling.filters.context: + context_visible_first: true + escapes: '\\[\\`]' + delimiters: + # Ignore front matter + - open: '(?s)^---' + close: '^---' + # Ignore code blocks + - open: '(?s)^(?P`{3,}).*$' + close: '^(?P=open)$' + # Ignore inline code + - open: '`' + close: '`' + # Ignore URLs + - open: '\(' + content: 'https?://[^\)]*' + close: '\)' + # Ignore email addresses + - open: '<' + content: '[^>]+@[^>]+' + close: '>' + - pyspelling.filters.url: +EOF +``` + +**Important**: Do not commit this local `.pyspelling.yml` override, as the repository default uses Hunspell for Rocky Linux 9 and 10 compatibility. + +#### Step 7: Install Pre-commit Hooks + +```bash +~/.local/bin/pre-commit install +``` + +**Note**: When using `pip install --user`, the `pre-commit` binary is installed to `~/.local/bin/`. You can either use the full path or add `~/.local/bin` to your PATH: + +```bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc +source ~/.bashrc +``` + +#### Step 8: Verify Your Setup + +Run all validation checks to confirm everything is working: + +```bash +~/.local/bin/pre-commit run --all-files +``` + +#### Step 9: Validate Your Document + +Before submitting your documentation, validate your specific file to ensure it passes all checks: + +```bash +# Spell check +pyspelling -n Markdown -S "docs/guides/your-document.md" + +# Markdown lint +markdownlint "docs/guides/your-document.md" + +# Link check +lychee "docs/guides/your-document.md" --no-progress +``` + +### macOS Sequoia Setup + +If you are running macOS Sequoia (macOS 15), follow these steps to set up a complete documentation validation environment. These instructions have been tested on both Apple Silicon (M1/M2/M3/M4) and Intel Macs. + +#### Step 1: Install Xcode Command Line Tools + +Before installing Homebrew, you must install the Xcode Command Line Tools: + +```bash +xcode-select --install +``` + +A dialog box will appear asking you to install the tools. Click **Install** and wait for the installation to complete. + +#### Step 2: Install Homebrew (if not already installed) + +If you do not have [Homebrew](https://brew.sh/) installed, run: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +**Important for Apple Silicon Macs (M1/M2/M3/M4)**: Homebrew installs to `/opt/homebrew` on Apple Silicon, which is not in the default PATH. After installation, run these commands to configure your shell: + +```bash +(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile +eval "$(/opt/homebrew/bin/brew shellenv)" +``` + +Verify Homebrew is working: + +```bash +brew doctor +``` + +**Note for Intel Macs**: Homebrew installs to `/usr/local` on Intel Macs, which is already in the default PATH. No additional configuration is needed. + +#### Step 3: Install System Dependencies + +```bash +brew install git python node aspell lychee +``` + +#### Step 4: Install Python Packages + +The recommended approach is to use a virtual environment: + +```bash +python3 -m venv ~/rocky-docs-env +source ~/rocky-docs-env/bin/activate +pip install pre-commit pyspelling +``` + +Add an alias to your shell configuration for easy activation: + +```bash +echo "alias rocky-docs-env='source ~/rocky-docs-env/bin/activate'" >> ~/.zshrc +source ~/.zshrc +``` + +#### Step 5: Install Node.js Packages + +If you encounter permission errors with npm global installs, configure npm to use a user directory: + +```bash +mkdir -p ~/.npm-global +npm config set prefix '~/.npm-global' +echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc +source ~/.zshrc +``` + +Then install markdownlint: + +```bash +npm install -g markdownlint-cli +``` + +#### Step 6: Clone your Forked Repository and Configure it + +```bash +git clone https://github.com/YOUR_USERNAME/documentation.git +cd documentation +``` + +Add the upstream remote: + +```bash +git remote add upstream https://github.com/rocky-linux/documentation.git +``` + +#### Step 7: Configure Pyspelling for macOS + +The repository `.pyspelling.yml` is configured for Hunspell by default. macOS uses Aspell (installed via Homebrew), so you need to create a local override. Create a `.pyspelling.yml` file in the repository root configured for Aspell: + +```bash +cat > .pyspelling.yml << 'EOF' +spellchecker: aspell +matrix: + - name: Markdown + sources: + - 'docs/**/*.md' + expect_match: false + aspell: + lang: en + d: en_US + dictionary: + wordlists: + - .wordlist.txt + output: build/spelling-wordlist.dic + pipeline: + - pyspelling.filters.markdown + - pyspelling.filters.html: + ignores: + - code + - pre + - kbd + - pyspelling.filters.context: + context_visible_first: true + escapes: '\\[\\`]' + delimiters: + - open: '(?s)^---' + close: '^---' + - open: '(?s)^(?P`{3,}).*$' + close: '^(?P=open)$' + - open: '`' + close: '`' + - open: '\(' + content: 'https?://[^\)]*' + close: '\)' + - open: '<' + content: '[^>]+@[^>]+' + close: '>' + - pyspelling.filters.url +EOF +``` + +**Important**: Do not commit this local `.pyspelling.yml` override, as the repository default uses Hunspell for Rocky Linux 9 and 10 compatibility. + +#### Step 8: Install Pre-commit Hooks + +```bash +pre-commit install +``` + +#### Step 9: Verify Your Setup + +Run the validation checks: + +```bash +pre-commit run --all-files +``` + +**Note**: The pyspelling (spell check) and lychee (link check) hooks are configured as manual hooks to avoid long run times on the full repository. When running `pre-commit run --all-files`, you may see markdownlint errors from existing repository files. These are pre-existing issues and are not your responsibility to fix. + +#### Validating Your Own Documents + +When contributing, validate your specific document using these commands: + +```bash +# Activate the virtual environment first +rocky-docs-env + +# Markdown lint check +markdownlint docs/guides/your-document.md + +# Spell check +pyspelling -n Markdown -S docs/guides/your-document.md + +# Link check +lychee docs/guides/your-document.md --no-progress +``` + +### Windows 11 Setup + +If you are running Windows 11, follow these steps to set up a complete documentation validation environment. + +#### Step 1: Install Chocolatey Package Manager + +Open **PowerShell as Administrator** (right-click Start → Terminal (Admin)) and run: + +```powershell +Set-ExecutionPolicy Bypass -Scope Process -Force +iwr https://community.chocolatey.org/install.ps1 -UseBasicParsing | iex +``` + +Close and reopen PowerShell as Administrator after installation. + +#### Step 2: Install Git, Python, and Node.js + +```powershell +choco install -y git python nodejs-lts +``` + +Close and reopen PowerShell as Administrator to refresh the PATH. + +#### Step 3: Install Python Packages + +```powershell +pip install pre-commit pyspelling +``` + +#### Step 4: Install Node.js Packages + +```powershell +npm install -g markdownlint-cli +``` + +#### Step 5: Install Hunspell (Spell Checker) + +```powershell +choco install -y hunspell.portable +``` + +#### Step 6: Install Lychee (Link Checker) + +```powershell +choco install -y lychee +``` + +#### Step 7: Clone your Forked Repository and Configure it + +```powershell +cd ~\Documents +git clone https://github.com/YOUR_USERNAME/documentation.git +cd documentation +``` + +#### Step 8: Create Pre-commit Configuration + +Create a `.pre-commit-config.yaml` file in the repository root: + +```powershell +@" +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + args: [--markdown-linebreak-ext=md] + - id: end-of-file-fixer + - id: check-yaml + exclude: | + (?x)^( + tools/mkdocs-docker\.yml| + tools/docker-compose\.yml| + build_pdf/build_base\.yml| + mkdocs\.yml + )$ + - id: check-added-large-files + args: ['--maxkb=1024'] + + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.38.0 + hooks: + - id: markdownlint + args: + - --config + - .markdownlint.yml + - --fix + files: \.md$ + exclude: | + (?x)^( + LICENSE\.md| + build_pdf/.* + )$ +"@ | Out-File -FilePath .pre-commit-config.yaml -Encoding UTF8 +``` + +#### Step 9: Install Pre-commit Hooks + +```powershell +pre-commit install +``` + +#### Step 10: Verify Your Setup + +Run validation checks to confirm everything is working: + +```powershell +pre-commit run --files docs/guides/automation/kickstart-rocky.md +``` + +### Install Pre-commit Hooks (Required) + +Pre-commit hooks run automatically before each commit to check spelling, markdown formatting, and links. You must set these up before contributing. + +**Platform-specific setup guides** - Follow the appropriate section instead of the general instructions below: + +- [Rocky Linux 10 Setup](#rocky-linux-10-setup) - Uses Hunspell, npm bundled with nodejs +- [Rocky Linux 9 Setup](#rocky-linux-9-setup) - Uses Hunspell (aspell not available in EPEL) +- [Rocky Linux 8 Setup](#rocky-linux-8-setup) - Uses Aspell, requires Python 3.9 and Node.js 18 module +- [macOS Sequoia Setup](#macos-sequoia-setup) - Uses Homebrew and Aspell +- [Windows 11 Setup](#windows-11-setup) - Uses Chocolatey, Hunspell, and PowerShell + +1. Install pre-commit: + +```bash +pip install pre-commit +``` + +2. Install the required tools: + +```bash +# Install pyspelling for spell checking +pip install pyspelling + +# Install aspell dictionaries (varies by OS) +# On Rocky Linux / RHEL / Fedora: +sudo dnf install aspell aspell-en + +# On Debian / Ubuntu: +sudo apt-get install aspell aspell-en + +# On macOS: +brew install aspell + +# Install markdownlint-cli for markdown linting +npm install -g markdownlint-cli + +# Install lychee for link checking +# On Rocky Linux 10 (binary installation - lychee is not in repos): +cd /tmp && curl -sLO https://github.com/lycheeverse/lychee/releases/latest/download/lychee-x86_64-unknown-linux-gnu.tar.gz +tar xzf lychee-x86_64-unknown-linux-gnu.tar.gz && sudo mv lychee /usr/local/bin/ +sudo chmod +x /usr/local/bin/lychee && rm -f lychee-x86_64-unknown-linux-gnu.tar.gz + +# On Fedora (may be available in repos): +sudo dnf install lychee + +# On Debian / Ubuntu (via cargo): +cargo install lychee + +# On macOS: +brew install lychee +``` + +3. Install the pre-commit hooks: + +```bash +pre-commit install +``` + +4. Verify the installation by running hooks manually: + +```bash +pre-commit run --all-files +``` + +## Creating New Documentation + +### Document Naming + +Use lowercase filenames with underscores or hyphens. Keep names short and descriptive: + +- `kickstart_rocky.md` - Good +- `HowToInstallRockyLinuxUsingKickstart.md` - Too long +- `ks.md` - Too vague + +For translated documents, append the language code before `.md`: + +- `kickstart_rocky.md` - English (default) +- `kickstart_rocky.de.md` - German +- `kickstart_rocky.es.md` - Spanish + +### Document Location + +Place your document in the appropriate directory under `docs/guides/`: + +| Topic | Directory | +|-------|-----------| +| Automation tasks | `docs/guides/automation/` | +| Backup solutions | `docs/guides/backup/` | +| Cloud deployments | `docs/guides/cloud/` | +| Content management | `docs/guides/cms/` | +| Communication tools | `docs/guides/communications/` | +| Container technologies | `docs/guides/containers/` | +| Contributing guides | `docs/guides/contribute/` | +| Database systems | `docs/guides/database/` | +| Desktop environments | `docs/guides/desktop/` | +| DNS configuration | `docs/guides/dns/` | +| Text editors | `docs/guides/editors/` | +| Email servers | `docs/guides/email/` | +| File sharing | `docs/guides/file_sharing/` | +| Hardware guides | `docs/guides/hardware/` | +| Interoperability | `docs/guides/interoperability/` | +| Kernel topics | `docs/guides/kernel/` | +| Mirror management | `docs/guides/mirror_management/` | +| Networking | `docs/guides/network/` | +| Package management | `docs/guides/package_management/` | +| Proxy servers | `docs/guides/proxies/` | +| Repositories | `docs/guides/repositories/` | +| Security | `docs/guides/security/` | +| Troubleshooting | `docs/guides/troubleshooting/` | +| Virtualization | `docs/guides/virtualization/` | +| Web servers | `docs/guides/web/` | + +If your guide does not fit any existing category, place it in the most relevant directory or ask the documentation team in the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). + +### Document Structure + +Every document must include front matter metadata at the top: + +```yaml +--- +title: Your Document Title +author: Your Name +contributors: Comma, Separated, Names +tested_with: 8.10, 9.7, 10.1 +tags: + - relevant + - tags + - here +--- +``` + +After the front matter, structure your document with: + +1. A brief introduction explaining what the guide covers +2. Prerequisites or requirements +3. Step-by-step instructions +4. Conclusion or summary + +### Example Guides + +Feel free to take a look at some example gudes to understand the formatting and styling: + +- [Kickstart Files and Rocky Linux](https://docs.rockylinux.org/guides/automation/kickstart-rocky/) +- [Setting Up libvirt on Rocky Linux](https://docs.rockylinux.org/guides/virtualization/libvirt-rocky/) +- [Automatic template creation with Packer and deployment with Ansible in a VMware vSphere environment](https://docs.rockylinux.org/guides/automation/templates-automation-packer-vsphere/) + +### AI Usage + +The Rocky Linux Documentation Team permits AI and LLM tools in the contribution process, following the [Fedora AI Policy](https://docs.fedoraproject.org/en-US/docs/ai-policy/) as a baseline. If you use AI for any part of your documentation (drafting, research, grammar, code generation), you must include a disclosure at the beginning of your document stating that AI was used and that you take full responsibility for correctness of the content. You must test every procedure and verify all technical content yourself, as AI frequently produces errors. Do not pass other contributors' existing work through AI tools and resubmit it as a contribution, as this erases the original author's voice. Minor corrections such as typos and broken links do not require disclosure. + +## Formatting Guidelines + +### Style Guide + +Follow the [Rocky Linux Style Guide](https://docs.rockylinux.org/guides/contribute/style_guide/) for: + +- Grammar and punctuation standards +- Voice and tone guidelines +- Accessibility requirements + +Key points: + +- Use US English spelling +- Use active voice +- Avoid contractions (aids translation) +- Use sentence-style capitalization for headings +- Use serial commas ("apples, oranges, and bananas") + +### Markdown Formatting + +Follow the [Document Formatting Guide](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) for: + +- Admonitions (note, warning, tip boxes) +- Code blocks +- Tables +- Lists + +Key rules enforced by our linter: + +- Use dashes (`-`) for unordered lists, not asterisks +- Include blank lines around headings +- Use fenced code blocks with language identifiers +- Avoid trailing whitespace +- End files with a single newline + +### Code Blocks + +Always specify the language for syntax highlighting: + +````markdown +```bash +dnf install httpd +systemctl enable --now httpd +``` +```` + +For commands where output is shown, use `text` as the language: + +````markdown +```text +$ hostname +rocky.example.com +``` +```` + +## Validation Checks + +Before committing, the pre-commit hooks automatically run: + +1. **Spell check** (pyspelling) - Checks for US English spelling errors +2. **Markdown lint** (markdownlint) - Validates markdown formatting +3. **Link check** (lychee) - Verifies all links are valid + +If any check fails, the commit is blocked. Fix the issues and try again. + +### Running Checks Manually + +Run all checks: + +```bash +pre-commit run --all-files +``` + +Run individual checks: + +```bash +# Spell check only +pyspelling + +# Markdown lint only +markdownlint docs/ + +# Link check only +lychee docs/ +``` + +### Rocky Docs Contribution Guidelines Validation + +Beyond the standard checks, your document must comply with the [Rocky Linux Documentation Contribution Guidelines](https://docs.rockylinux.org/guides/contribute/) and [Formatting Standards](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/). Use the following checks to validate your document before submitting a pull request. + +#### Validate a Single Document + +Replace `path/to/your-document.md` with your document path in all commands below. + +**Run standard checks on your document:** + +```bash +# Spell check +pyspelling -n Markdown -S "path/to/your-document.md" + +# Markdown lint +markdownlint "path/to/your-document.md" + +# Link check +lychee "path/to/your-document.md" --no-progress +``` + +#### Metadata Validation + +Every document requires front matter metadata. Check that your document includes: + +| Field | Required | Description | +|-------|----------|-------------| +| `title` | Yes | Document title | +| `author` | Yes | Your name | +| `contributors` | Recommended | Comma-separated list of contributors | +| `tested_with` | Yes | Rocky Linux versions tested (e.g., `8.10, 9.7, 10.1`) | +| `tags` | Yes | Searchable one-word terms | + +**Check for required metadata:** + +```bash +# Check for title +grep -q '^title:' path/to/your-document.md && echo "✓ Title found" || echo "✗ Missing title" + +# Check for author +grep -q '^author:' path/to/your-document.md && echo "✓ Author found" || echo "✗ Missing author" + +# Check for contributors (recommended) +grep -q '^contributors:' path/to/your-document.md && echo "✓ Contributors found" || echo "⚠ Contributors recommended" + +# Check for tested with +grep -qE '^tested.*(with|_with|on)?:' path/to/your-document.md && echo "✓ Tested with found" || echo "✗ Missing tested with" + +# Check for tags +grep -q '^tags:' path/to/your-document.md && echo "✓ Tags found" || echo "✗ Missing tags" +``` + +#### Heading Structure Validation + +Documents should have at most one Level 1 heading (`#`). If your document has `title:` metadata, the title is auto-generated, so you may not need a Level 1 heading at all. + +```bash +# Count Level 1 headings (should be 0 or 1) +h1_count=$(grep -c '^# ' path/to/your-document.md || echo 0) +if [ "$h1_count" -le 1 ]; then + echo "✓ Heading structure OK ($h1_count H1 headings)" +else + echo "✗ Too many H1 headings: $h1_count (maximum 1 allowed)" +fi +``` + +#### Admonition Formatting + +Admonitions use the `!!!` syntax with proper types and 4-space indentation for content: + +```markdown +!!! warning "Optional Custom Title" + + This content must be indented with 4 spaces. +``` + +Valid admonition types: `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote` + +```bash +# Check admonition syntax +if grep -qE '^!!!\s+(note|abstract|info|tip|success|question|warning|failure|danger|bug|example|quote)' path/to/your-document.md; then + echo "✓ Admonitions use valid types" +else + if grep -q '^!!!' path/to/your-document.md; then + echo "⚠ Admonitions found but may have invalid types" + else + echo "ℹ No admonitions found" + fi +fi +``` + +#### Code Block Validation + +Code blocks must specify a language identifier for syntax highlighting: + +````markdown +```bash +dnf install httpd +``` +```` + +```bash +# Check for code blocks without language identifiers +blocks_without_lang=$(grep -c '^```$' path/to/your-document.md 2>/dev/null || echo 0) +blocks_with_lang=$(grep -c '^```[a-zA-Z]' path/to/your-document.md 2>/dev/null || echo 0) + +if [ "$blocks_without_lang" -eq 0 ]; then + echo "✓ All code blocks have language identifiers ($blocks_with_lang blocks)" +else + echo "✗ $blocks_without_lang code blocks missing language identifiers" +fi +``` + +#### Link Format Validation + +Links should use proper markdown format `[text](url)`. Avoid bare URLs. + +```bash +# Count properly formatted links +proper_links=$(grep -oE '\[[^]]+\]\([^)]+\)' path/to/your-document.md 2>/dev/null | wc -l) +echo "ℹ Found $proper_links properly formatted links" +``` + +#### Lab Domain Validation + +When using example URLs in documentation, use approved domains to pass link validation: + +- `example.com`, `example.org`, `example.net` +- `home.arpa` +- `localhost` or `127.0.0.1` + +#### Internal Anchors Warning + +Avoid internal document anchors like `[link](#section-name)` as they may break during translation. + +```bash +# Check for internal anchors +anchors=$(grep -cE '\[.+\]\(#[^)]+\)' path/to/your-document.md 2>/dev/null || echo 0) +if [ "$anchors" -eq 0 ]; then + echo "✓ No internal anchors found" +else + echo "⚠ Found $anchors internal anchors (may break during translation)" +fi +``` + +#### Raw HTML Warning + +Avoid using raw HTML elements. Markdown linters flag them and they may not render correctly. The following HTML elements are allowed in `.markdownlint.yml` and will not trigger linting errors: + +- `` and `` - For subscript and superscript text +- `
` and `` - For collapsible/expandable content sections + +```bash +# Check for HTML tags (excluding allowed elements: sub, sup, details, summary) +html_tags=$(grep -cE '<(?!sub|sup|details|summary|/sub|/sup|/details|/summary)[a-zA-Z][^>]*>' path/to/your-document.md 2>/dev/null || echo 0) +if [ "$html_tags" -eq 0 ]; then + echo "✓ No disallowed raw HTML found" +else + echo "⚠ Found $html_tags HTML tags (use markdown instead, or allowed elements: sub, sup, details, summary)" +fi +``` + +#### Complete Validation Script + +Save this script as `validate-doc.sh` and run it against your document: + +```bash +#!/bin/bash +# Rocky Linux Documentation Validator +# Usage: ./validate-doc.sh path/to/your-document.md + +if [ -z "$1" ]; then + echo "Usage: $0 " + exit 1 +fi + +DOC="$1" + +if [ ! -f "$DOC" ]; then + echo "Error: File not found: $DOC" + exit 1 +fi + +echo "============================================" +echo "ROCKY LINUX DOCUMENTATION VALIDATOR" +echo "============================================" +echo "Document: $DOC" +echo "--------------------------------------------" +echo "" +echo "METADATA CHECKS:" +echo "--------------------------------------------" +grep -q '^title:' "$DOC" && echo " Title: ✓ PASS" || echo " Title: ✗ FAIL - Required" +grep -q '^author:' "$DOC" && echo " Author: ✓ PASS" || echo " Author: ✗ FAIL - Required" +grep -q '^contributors:' "$DOC" && echo " Contributors: ✓ PASS" || echo " Contributors: ⚠ WARN - Recommended" +grep -qE '^tested.*(with|_with|on)?:' "$DOC" && echo " Tested With: ✓ PASS" || echo " Tested With: ✗ FAIL - Required" +grep -q '^tags:' "$DOC" && echo " Tags: ✓ PASS" || echo " Tags: ✗ FAIL - Required" +echo "" +echo "STRUCTURE CHECKS:" +echo "--------------------------------------------" +h1_count=$(grep -c '^# ' "$DOC" 2>/dev/null || echo 0) +if [ "$h1_count" -le 1 ]; then + echo " Single H1: ✓ PASS ($h1_count heading)" +else + echo " Single H1: ✗ FAIL - Found $h1_count (max 1)" +fi +echo "" +echo "FORMATTING CHECKS:" +echo "--------------------------------------------" +blocks_without_lang=$(grep -c '^```$' "$DOC" 2>/dev/null || echo 0) +if [ "$blocks_without_lang" -eq 0 ]; then + echo " Code Blocks: ✓ PASS" +else + echo " Code Blocks: ✗ FAIL - $blocks_without_lang missing language" +fi + +anchors=$(grep -cE '\[.+\]\(#[^)]+\)' "$DOC" 2>/dev/null || echo 0) +if [ "$anchors" -eq 0 ]; then + echo " No Anchors: ✓ PASS" +else + echo " No Anchors: ⚠ WARN - $anchors found (translation risk)" +fi + +html_tags=$(grep -cE '<(?!sub|sup|details|summary|/sub|/sup|/details|/summary)[a-zA-Z][^>]*>' "$DOC" 2>/dev/null || echo 0) +if [ "$html_tags" -eq 0 ]; then + echo " No Raw HTML: ✓ PASS (sub, sup, details, summary are allowed)" +else + echo " No Raw HTML: ⚠ WARN - $html_tags disallowed tags found" +fi +echo "" +echo "TOOL CHECKS:" +echo "--------------------------------------------" +echo "Running pyspelling..." +if pyspelling -n Markdown -S "$DOC" > /dev/null 2>&1; then + echo " Spell Check: ✓ PASS" +else + echo " Spell Check: ✗ FAIL - Run: pyspelling -n Markdown -S \"$DOC\"" +fi + +echo "Running markdownlint..." +if markdownlint "$DOC" > /dev/null 2>&1; then + echo " Markdown: ✓ PASS" +else + echo " Markdown: ✗ FAIL - Run: markdownlint \"$DOC\"" +fi + +echo "Running lychee..." +if lychee "$DOC" --no-progress > /dev/null 2>&1; then + echo " Links: ✓ PASS" +else + echo " Links: ✗ FAIL - Run: lychee \"$DOC\" --no-progress" +fi +echo "" +echo "============================================" +``` + +Make the script executable and run it: + +```bash +chmod +x validate-doc.sh +./validate-doc.sh docs/guides/automation/kickstart-rocky.md +``` + +Example output: + +```text +============================================ +ROCKY LINUX DOCUMENTATION VALIDATOR +============================================ +Document: docs/guides/automation/kickstart-rocky.md +-------------------------------------------- + +METADATA CHECKS: +-------------------------------------------- + Title: ✓ PASS + Author: ✓ PASS + Contributors: ✓ PASS + Tested With: ✓ PASS + Tags: ✓ PASS + +STRUCTURE CHECKS: +-------------------------------------------- + Single H1: ✓ PASS (1 heading) + +FORMATTING CHECKS: +-------------------------------------------- + Code Blocks: ✓ PASS + No Anchors: ✓ PASS + No Raw HTML: ✓ PASS + +TOOL CHECKS: +-------------------------------------------- +Running pyspelling... + Spell Check: ✓ PASS +Running markdownlint... + Markdown: ✓ PASS +Running lychee... + Links: ✓ PASS + +============================================ +``` + +### Adding Words to the Dictionary + +If the spell checker flags a valid technical term, add it to `.wordlist.txt` in alphabetical order. Common additions include: + +- Rocky Linux specific terms +- Package names +- Technical acronyms +- Command names + +**Important**: Do not include `.wordlist.txt` changes in your pull request. Keep your wordlist additions local to your machine. The documentation team maintains the shared `.wordlist.txt` and will add any necessary terms during the review process. When staging files for your commit, only add your document: + +```bash +# Only stage your document, not the wordlist +git add docs/guides/your-document.md +``` + +If you have already staged `.wordlist.txt` by mistake, unstage it before committing: + +```bash +git restore --staged .wordlist.txt +``` + +## Submitting a Pull Request + +### Pushing Your Changes to the Rocky Linux Documentation Repository + +1. Sync your fork with upstream: + +```bash +git fetch upstream +git checkout main +git merge upstream/main +``` + +2. Create a branch for your changes: + +```bash +git checkout -b your-new-document +``` + +3. Add your document and commit: + +```bash +git add docs/guides/your-document.md +git commit -m "Add new document for your-document" +``` + +4. Push and create a pull request: + +```bash +git push origin your-new-document +``` + +> **Note:** You can also edit existing documentation and push your changes to the Rocky Linux Documentation repository using the same method. + +## Getting Help + +- **Mattermost**: Join the [Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation) and the community of contributors will be more than happy to help you with your document. +- **GitHub Issues**: Report documentation bugs or suggest improvements +- **Forums**: Visit the [Rocky Linux Forums](https://forums.rockylinux.org) for general questions + +## Additional Resources + +- [Style Guide](https://docs.rockylinux.org/guides/contribute/style_guide/) - Writing standards +- [Document Formatting](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) - Markdown syntax and admonitions +- [Beginner Contributors Guide](https://docs.rockylinux.org/guides/contribute/beginners/) - Detailed walkthrough for new contributors +- [Creating New Documents](https://docs.rockylinux.org/guides/contribute/createnew/) - GitHub-specific instructions +- [Navigation and Structure](https://docs.rockylinux.org/guides/contribute/navigation/) - How the documentation site is organized + +## License + +Documents contributed to Rocky Linux documentation are published under the [Creative Commons BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/). By contributing, you agree to license your work under these terms. From b21893df3f450a02fd1504e5ff464bddd8740cc9 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Wed, 11 Feb 2026 08:34:01 -0600 Subject: [PATCH 02/14] Add contributors section to contributing.md I've added the ai-contributors section in the front matter. --- docs/guides/contribute/contributing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/contribute/contributing.md b/docs/guides/contribute/contributing.md index 5a775f26c8..328ecdba17 100644 --- a/docs/guides/contribute/contributing.md +++ b/docs/guides/contribute/contributing.md @@ -1,6 +1,8 @@ --- title: Contributing to the Rocky Linux Documentation author: Howard Van Der Wal +contributors: +ai-contributors: Claude Code tags: - contributing - documentation From 413fac1af4ad8221ca8257c6e461312de7b0d0d9 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 13:28:06 +0900 Subject: [PATCH 03/14] Rename to expert_contributing.md and address PR feedback - Rename contributing.md to expert_contributing.md - Update title to "An expert's guide to contributing" - Remove Table of Contents (breaks during translation) - Remove H1 heading (picked up from title: meta entry) - Apply sentence-style capitalization to all headers - Remove all internal anchor links (translation incompatible) - Add warm welcome section with community support messaging - Make clear the tooling setup is optional, not required - Reference beginner guide as starting point for new contributors - Add Zed editor to graphical editors list - Replace all docs.rockylinux.org URLs with relative references - Add git update-index --assume-unchanged for .pyspelling.yml overrides to prevent accidental commits Co-Authored-By: Claude Opus 4.6 --- ...contributing.md => expert_contributing.md} | 294 +++++++++--------- 1 file changed, 141 insertions(+), 153 deletions(-) rename docs/guides/contribute/{contributing.md => expert_contributing.md} (82%) diff --git a/docs/guides/contribute/contributing.md b/docs/guides/contribute/expert_contributing.md similarity index 82% rename from docs/guides/contribute/contributing.md rename to docs/guides/contribute/expert_contributing.md index 328ecdba17..421745b777 100644 --- a/docs/guides/contribute/contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -1,5 +1,5 @@ --- -title: Contributing to the Rocky Linux Documentation +title: An expert's guide to contributing author: Howard Van Der Wal contributors: ai-contributors: Claude Code @@ -9,69 +9,38 @@ tags: - guide --- -# Contributing to the Rocky Linux Documentation - -## AI Usage Disclosure +## AI usage disclosure This document was created with the assistance of AI. All content has been reviewed, tested, and verified by a human author. The author takes full responsibility for the accuracy and correctness of this document. ## Welcome -Thank you for your interest in contributing to the Rocky Linux documentation. This guide walks you through everything you need to create, edit, and submit documentation that meets our standards. - -## Table of Contents - -* [Quick Start](#quick-start) -* [Prerequisites](#prerequisites) -* [Fork and Clone the Repository](#fork-and-clone-the-repository) -* [Setting Up Your Environment](#setting-up-your-environment) - * [Alternative Tooling](#alternative-tooling) - * [Local Editors](#local-editors) - * [Rocky Linux 10 Setup](#rocky-linux-10-setup) - * [Rocky Linux 9 Setup](#rocky-linux-9-setup) - * [Rocky Linux 8 Setup](#rocky-linux-8-setup) - * [macOS Sequoia Setup](#macos-sequoia-setup) - * [Windows 11 Setup](#windows-11-setup) - * [Install Pre-commit Hooks (Required)](#install-pre-commit-hooks-required) -* [Creating New Documentation](#creating-new-documentation) - * [Document Naming](#document-naming) - * [Document Location](#document-location) - * [Document Structure](#document-structure) - * [Example Guides](#example-guides) - * [AI Usage](#ai-usage) -* [Formatting Guidelines](#formatting-guidelines) - * [Style Guide](#style-guide) - * [Markdown Formatting](#markdown-formatting) - * [Code Blocks](#code-blocks) -* [Validation Checks](#validation-checks) - * [Running Checks Manually](#running-checks-manually) - * [Rocky Docs Contribution Guidelines Validation](#rocky-docs-contribution-guidelines-validation) - * [Adding Words to the Dictionary](#adding-words-to-the-dictionary) -* [Submitting a Pull Request](#submitting-a-pull-request) -* [Getting Help](#getting-help) -* [Additional Resources](#additional-resources) -* [License](#license) - -## Quick Start +Thank you for your interest in contributing to the Rocky Linux documentation. Whether you are writing new guides, translating existing content, editing for clarity, or reviewing pull requests, every contribution matters and is deeply valued by the community. + +This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional.** You do not need any of this to contribute to the Rocky Linux documentation. If you are new to contributing, the [Beginner contributors guide](beginners.md) is a great place to start. You can also edit documentation directly on GitHub without installing anything locally. + +No matter your experience level, the Rocky Linux community is here to help. If you have questions, run into problems, or just want guidance on where to start, reach out on the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). Someone will be happy to help you get started. + +## Quick start 1. Fork the [Rocky Linux Documentation repository](https://github.com/rocky-linux/documentation) 2. Clone your fork locally -3. Set up pre-commit hooks (required) +3. Set up pre-commit hooks (optional but recommended) 4. Create or edit documentation 5. Run validation checks 6. Submit a pull request ## Prerequisites -Before contributing, you need: +Before setting up the local validation environment, you need: - A [GitHub account](https://github.com/signup) - [Git](https://git-scm.com/downloads) installed on your machine - [Python 3.8+](https://www.python.org/downloads/) for spell checking - [Node.js](https://nodejs.org/) for markdown linting -- A text editor (see [Local Editors](#local-editors) below) +- A text editor (see the local editors section below) -## Fork and Clone the Repository +## Fork and clone the repository 1. Navigate to the [Rocky Linux documentation repository](https://github.com/rocky-linux/documentation) 2. Click the **Fork** button in the upper right corner @@ -88,9 +57,9 @@ cd documentation git remote add upstream https://github.com/rocky-linux/documentation.git ``` -## Setting Up Your Environment +## Setting up your environment -### Alternative Tooling +### Alternative tooling The setup instructions in this section describe one approach to documentation validation using pre-commit hooks and command-line tools. There are other methods available to check your markdown documents, before submitting them as a PR. @@ -103,21 +72,22 @@ If you already use a terminal-based editor (Neovim, Emacs, Helix, etc.) with int These tools provide the same validation capabilities and can be configured to match the Rocky Linux documentation standards. The key requirement is that your contributions pass the automated CI checks when you submit a pull request, regardless of which tools you use locally. -### Local Editors +### Local editors Choose a markdown editor that suits your workflow: -#### Graphical Editors +#### Graphical editors - [ReText](https://github.com/retext-project/retext) - Free, cross-platform, open source - [Zettlr](https://www.zettlr.com/) - Free, cross-platform, open source - [MarkText](https://github.com/marktext/marktext) - Free, cross-platform, open source - [Remarkable](https://remarkableapp.github.io/) - Linux and Windows, open source +- [Zed](https://zed.dev/) - Free, cross-platform, open source, written in Rust. Plugins available for vale, marksman, harper-ls, and markdownlint - [VS Code](https://code.visualstudio.com/) - Partially open source, by Microsoft. Recommended extensions: Git Graph, Markdown All in One, Markdown Preview Enhanced, markdownlint -#### Terminal Editors +#### Terminal editors -- [NvChad](https://nvchad.com/) - For Neovim users. See our [NvChad setup guide](https://docs.rockylinux.org/books/nvchad/) +- [NvChad](https://nvchad.com/) - For Neovim users. See our [NvChad setup guide](../../../books/nvchad/index.md) - [Doom Emacs](https://github.com/doomemacs/doomemacs) - For Emacs users. Enable the `markdown` module in your config Terminal editors can integrate the same validation tools used by the pre-commit hooks directly into your editing workflow: @@ -127,30 +97,30 @@ Terminal editors can integrate the same validation tools used by the pre-commit - [harper-ls](https://github.com/Automattic/harper) - [ltex-ls](https://github.com/valentjn/ltex-ls) -### Rocky Linux 10 Setup +### Rocky Linux 10 setup If you are running Rocky Linux 10, follow these steps to set up a complete documentation validation environment. This installs all required tools and enables you to run the same checks that the Documentation Team uses to validate pull requests. -#### Step 1: Install System Dependencies +#### Step 1: Install system dependencies ```bash # Note: npm is bundled with nodejs in Rocky Linux 10 sudo dnf install -y git python3-pip hunspell hunspell-en-US nodejs ``` -#### Step 2: Install Python Packages +#### Step 2: Install Python packages ```bash pip install pre-commit pyspelling ``` -#### Step 3: Install Node.js Packages +#### Step 3: Install Node.js packages ```bash sudo npm install -g markdownlint-cli ``` -#### Step 4: Install Lychee Link Checker +#### Step 4: Install lychee link checker Lychee is not available in the Rocky Linux repositories, so install the binary directly: @@ -169,7 +139,7 @@ Verify the installation: lychee --version ``` -#### Step 5: Clone your Forked Repository and Configure it +#### Step 5: Clone your forked repository and configure it ```bash git clone https://github.com/YOUR_USERNAME/documentation.git @@ -183,7 +153,7 @@ cd documentation git pull origin main ``` -#### Step 6: Verify Pyspelling Configuration +#### Step 6: Verify pyspelling configuration The repository includes a `.pyspelling.yml` configured for Hunspell, which is the default spell checker on Rocky Linux 10. No additional configuration is needed. Verify that Hunspell is installed: @@ -197,13 +167,13 @@ If not installed: sudo dnf install -y hunspell hunspell-en-US ``` -#### Step 7: Install Pre-commit Hooks +#### Step 7: Install pre-commit hooks ```bash pre-commit install ``` -#### Step 8: Verify Your Setup +#### Step 8: Verify your setup Run all validation checks to confirm everything is working: @@ -211,7 +181,7 @@ Run all validation checks to confirm everything is working: pre-commit run --all-files ``` -#### Expected Behavior on First Run +#### Expected behavior on first run When running `pre-commit run --all-files` for the first time, you may see errors from existing repository files. This is expected behavior: @@ -227,7 +197,7 @@ When running `pre-commit run --all-files` for the first time, you may see errors **Important**: The markdownlint errors you see are in existing repository documentation files, not files you created. When contributing, you only need to ensure your own files pass validation. -#### Step 9: Validate Your Document +#### Step 9: Validate your document Before submitting your documentation, validate your specific file to ensure it passes all checks: @@ -264,29 +234,29 @@ lychee docs/guides/hpc/slurm-rocky.md --no-progress 🔍 8 Total (in 0s) ✅ 8 OK 🚫 0 Errors ``` -### Rocky Linux 9 Setup +### Rocky Linux 9 setup If you are running Rocky Linux 9, follow these steps to set up a complete documentation validation environment. Rocky Linux 9 uses Hunspell for spell checking (aspell is not available in EPEL for Rocky Linux 9). -#### Step 1: Install System Dependencies +#### Step 1: Install system dependencies ```bash sudo dnf install -y git python3-pip hunspell hunspell-en-US nodejs npm ``` -#### Step 2: Install Python Packages +#### Step 2: Install Python packages ```bash pip install --user pre-commit pyspelling ``` -#### Step 3: Install Node.js Packages +#### Step 3: Install Node.js packages ```bash sudo npm install -g markdownlint-cli ``` -#### Step 4: Install Lychee Link Checker +#### Step 4: Install lychee link checker Lychee is not available in the Rocky Linux repositories, so install the binary directly: @@ -305,14 +275,14 @@ Verify the installation: lychee --version ``` -#### Step 5: Clone your Forked Repository and Configure it +#### Step 5: Clone your forked repository and configure it ```bash git clone https://github.com/YOUR_USERNAME/documentation.git cd documentation ``` -#### Step 6: Verify Pyspelling Configuration +#### Step 6: Verify pyspelling configuration The repository includes a `.pyspelling.yml` configured for Hunspell, which is the default spell checker on Rocky Linux 9. No additional configuration is needed. Verify that Hunspell is installed: @@ -326,7 +296,7 @@ If not installed: sudo dnf install -y hunspell hunspell-en-US ``` -#### Step 7: Install Pre-commit Hooks +#### Step 7: Install pre-commit hooks ```bash ~/.local/bin/pre-commit install @@ -339,7 +309,7 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` -#### Step 8: Verify Your Setup +#### Step 8: Verify your setup Run all validation checks to confirm everything is working: @@ -347,7 +317,7 @@ Run all validation checks to confirm everything is working: ~/.local/bin/pre-commit run --all-files ``` -#### Step 9: Validate Your Document +#### Step 9: Validate your document Before submitting your documentation, validate your specific file to ensure it passes all checks: @@ -362,11 +332,11 @@ markdownlint "docs/guides/your-document.md" lychee "docs/guides/your-document.md" --no-progress ``` -### Rocky Linux 8 Setup +### Rocky Linux 8 setup If you are running Rocky Linux 8, follow these steps to set up a complete documentation validation environment. Rocky Linux 8 uses Aspell for spell checking (available from base repositories). -#### Step 1: Install System Dependencies +#### Step 1: Install system dependencies Rocky Linux 8 uses Python 3.9 and Node.js module streams: @@ -381,7 +351,7 @@ sudo dnf module enable -y nodejs:18 sudo dnf install -y nodejs ``` -#### Step 2: Install Python Packages +#### Step 2: Install Python packages Use Python 3.9's pip: @@ -389,13 +359,13 @@ Use Python 3.9's pip: pip3.9 install --user pre-commit pyspelling ``` -#### Step 3: Install Node.js Packages +#### Step 3: Install Node.js packages ```bash sudo npm install -g markdownlint-cli ``` -#### Step 4: Install Lychee Link Checker +#### Step 4: Install lychee link checker Lychee is not available in the Rocky Linux repositories, so install the binary directly: @@ -414,14 +384,14 @@ Verify the installation: lychee --version ``` -#### Step 5: Clone your Forked Repository and Configure it +#### Step 5: Clone your forked repository and configure it ```bash git clone https://github.com/YOUR_USERNAME/documentation.git cd documentation ``` -#### Step 6: Configure Pyspelling for Aspell +#### Step 6: Configure pyspelling for Aspell The repository `.pyspelling.yml` is configured for Hunspell by default. Rocky Linux 8 uses Aspell instead, so you need to create a local override. Create a `.pyspelling.yml` file in the repository root: @@ -474,9 +444,19 @@ matrix: EOF ``` -**Important**: Do not commit this local `.pyspelling.yml` override, as the repository default uses Hunspell for Rocky Linux 9 and 10 compatibility. +After creating the override, tell Git to ignore your local changes to this file so you do not accidentally commit it: + +```bash +git update-index --assume-unchanged .pyspelling.yml +``` + +This prevents the modified `.pyspelling.yml` from appearing in `git status` or being staged by `git add`. If you ever need to undo this (for example, to pull upstream changes to the file), run: + +```bash +git update-index --no-assume-unchanged .pyspelling.yml +``` -#### Step 7: Install Pre-commit Hooks +#### Step 7: Install pre-commit hooks ```bash ~/.local/bin/pre-commit install @@ -489,7 +469,7 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` -#### Step 8: Verify Your Setup +#### Step 8: Verify your setup Run all validation checks to confirm everything is working: @@ -497,7 +477,7 @@ Run all validation checks to confirm everything is working: ~/.local/bin/pre-commit run --all-files ``` -#### Step 9: Validate Your Document +#### Step 9: Validate your document Before submitting your documentation, validate your specific file to ensure it passes all checks: @@ -512,11 +492,11 @@ markdownlint "docs/guides/your-document.md" lychee "docs/guides/your-document.md" --no-progress ``` -### macOS Sequoia Setup +### macOS Sequoia setup If you are running macOS Sequoia (macOS 15), follow these steps to set up a complete documentation validation environment. These instructions have been tested on both Apple Silicon (M1/M2/M3/M4) and Intel Macs. -#### Step 1: Install Xcode Command Line Tools +#### Step 1: Install Xcode command line tools Before installing Homebrew, you must install the Xcode Command Line Tools: @@ -549,13 +529,13 @@ brew doctor **Note for Intel Macs**: Homebrew installs to `/usr/local` on Intel Macs, which is already in the default PATH. No additional configuration is needed. -#### Step 3: Install System Dependencies +#### Step 3: Install system dependencies ```bash brew install git python node aspell lychee ``` -#### Step 4: Install Python Packages +#### Step 4: Install Python packages The recommended approach is to use a virtual environment: @@ -572,7 +552,7 @@ echo "alias rocky-docs-env='source ~/rocky-docs-env/bin/activate'" >> ~/.zshrc source ~/.zshrc ``` -#### Step 5: Install Node.js Packages +#### Step 5: Install Node.js packages If you encounter permission errors with npm global installs, configure npm to use a user directory: @@ -589,7 +569,7 @@ Then install markdownlint: npm install -g markdownlint-cli ``` -#### Step 6: Clone your Forked Repository and Configure it +#### Step 6: Clone your forked repository and configure it ```bash git clone https://github.com/YOUR_USERNAME/documentation.git @@ -602,7 +582,7 @@ Add the upstream remote: git remote add upstream https://github.com/rocky-linux/documentation.git ``` -#### Step 7: Configure Pyspelling for macOS +#### Step 7: Configure pyspelling for macOS The repository `.pyspelling.yml` is configured for Hunspell by default. macOS uses Aspell (installed via Homebrew), so you need to create a local override. Create a `.pyspelling.yml` file in the repository root configured for Aspell: @@ -648,15 +628,25 @@ matrix: EOF ``` -**Important**: Do not commit this local `.pyspelling.yml` override, as the repository default uses Hunspell for Rocky Linux 9 and 10 compatibility. +After creating the override, tell Git to ignore your local changes to this file so you do not accidentally commit it: -#### Step 8: Install Pre-commit Hooks +```bash +git update-index --assume-unchanged .pyspelling.yml +``` + +This prevents the modified `.pyspelling.yml` from appearing in `git status` or being staged by `git add`. If you ever need to undo this (for example, to pull upstream changes to the file), run: + +```bash +git update-index --no-assume-unchanged .pyspelling.yml +``` + +#### Step 8: Install pre-commit hooks ```bash pre-commit install ``` -#### Step 9: Verify Your Setup +#### Step 9: Verify your setup Run the validation checks: @@ -666,7 +656,7 @@ pre-commit run --all-files **Note**: The pyspelling (spell check) and lychee (link check) hooks are configured as manual hooks to avoid long run times on the full repository. When running `pre-commit run --all-files`, you may see markdownlint errors from existing repository files. These are pre-existing issues and are not your responsibility to fix. -#### Validating Your Own Documents +#### Validating your own documents When contributing, validate your specific document using these commands: @@ -684,11 +674,11 @@ pyspelling -n Markdown -S docs/guides/your-document.md lychee docs/guides/your-document.md --no-progress ``` -### Windows 11 Setup +### Windows 11 setup If you are running Windows 11, follow these steps to set up a complete documentation validation environment. -#### Step 1: Install Chocolatey Package Manager +#### Step 1: Install Chocolatey package manager Open **PowerShell as Administrator** (right-click Start → Terminal (Admin)) and run: @@ -707,31 +697,31 @@ choco install -y git python nodejs-lts Close and reopen PowerShell as Administrator to refresh the PATH. -#### Step 3: Install Python Packages +#### Step 3: Install Python packages ```powershell pip install pre-commit pyspelling ``` -#### Step 4: Install Node.js Packages +#### Step 4: Install Node.js packages ```powershell npm install -g markdownlint-cli ``` -#### Step 5: Install Hunspell (Spell Checker) +#### Step 5: Install Hunspell (spell checker) ```powershell choco install -y hunspell.portable ``` -#### Step 6: Install Lychee (Link Checker) +#### Step 6: Install lychee (link checker) ```powershell choco install -y lychee ``` -#### Step 7: Clone your Forked Repository and Configure it +#### Step 7: Clone your forked repository and configure it ```powershell cd ~\Documents @@ -739,7 +729,7 @@ git clone https://github.com/YOUR_USERNAME/documentation.git cd documentation ``` -#### Step 8: Create Pre-commit Configuration +#### Step 8: Create pre-commit configuration Create a `.pre-commit-config.yaml` file in the repository root: @@ -780,13 +770,13 @@ repos: "@ | Out-File -FilePath .pre-commit-config.yaml -Encoding UTF8 ``` -#### Step 9: Install Pre-commit Hooks +#### Step 9: Install pre-commit hooks ```powershell pre-commit install ``` -#### Step 10: Verify Your Setup +#### Step 10: Verify your setup Run validation checks to confirm everything is working: @@ -794,17 +784,11 @@ Run validation checks to confirm everything is working: pre-commit run --files docs/guides/automation/kickstart-rocky.md ``` -### Install Pre-commit Hooks (Required) - -Pre-commit hooks run automatically before each commit to check spelling, markdown formatting, and links. You must set these up before contributing. +### Install pre-commit hooks -**Platform-specific setup guides** - Follow the appropriate section instead of the general instructions below: +Pre-commit hooks run automatically before each commit to check spelling, markdown formatting, and links. If you followed one of the platform-specific setup guides above, you have already completed this step. -- [Rocky Linux 10 Setup](#rocky-linux-10-setup) - Uses Hunspell, npm bundled with nodejs -- [Rocky Linux 9 Setup](#rocky-linux-9-setup) - Uses Hunspell (aspell not available in EPEL) -- [Rocky Linux 8 Setup](#rocky-linux-8-setup) - Uses Aspell, requires Python 3.9 and Node.js 18 module -- [macOS Sequoia Setup](#macos-sequoia-setup) - Uses Homebrew and Aspell -- [Windows 11 Setup](#windows-11-setup) - Uses Chocolatey, Hunspell, and PowerShell +For other platforms not listed above, here are the general instructions: 1. Install pre-commit: @@ -859,9 +843,9 @@ pre-commit install pre-commit run --all-files ``` -## Creating New Documentation +## Creating new documentation -### Document Naming +### Document naming Use lowercase filenames with underscores or hyphens. Keep names short and descriptive: @@ -875,7 +859,7 @@ For translated documents, append the language code before `.md`: - `kickstart_rocky.de.md` - German - `kickstart_rocky.es.md` - Spanish -### Document Location +### Document location Place your document in the appropriate directory under `docs/guides/`: @@ -909,7 +893,7 @@ Place your document in the appropriate directory under `docs/guides/`: If your guide does not fit any existing category, place it in the most relevant directory or ask the documentation team in the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). -### Document Structure +### Document structure Every document must include front matter metadata at the top: @@ -933,23 +917,23 @@ After the front matter, structure your document with: 3. Step-by-step instructions 4. Conclusion or summary -### Example Guides +### Example guides -Feel free to take a look at some example gudes to understand the formatting and styling: +Feel free to take a look at some example guides to understand the formatting and styling: -- [Kickstart Files and Rocky Linux](https://docs.rockylinux.org/guides/automation/kickstart-rocky/) -- [Setting Up libvirt on Rocky Linux](https://docs.rockylinux.org/guides/virtualization/libvirt-rocky/) -- [Automatic template creation with Packer and deployment with Ansible in a VMware vSphere environment](https://docs.rockylinux.org/guides/automation/templates-automation-packer-vsphere/) +- [Kickstart Files and Rocky Linux](../automation/kickstart-rocky.md) +- [Setting Up libvirt on Rocky Linux](../virtualization/libvirt-rocky.md) +- [Automatic template creation with Packer and deployment with Ansible in a VMware vSphere environment](../automation/templates-automation-packer-vsphere.md) -### AI Usage +### AI usage The Rocky Linux Documentation Team permits AI and LLM tools in the contribution process, following the [Fedora AI Policy](https://docs.fedoraproject.org/en-US/docs/ai-policy/) as a baseline. If you use AI for any part of your documentation (drafting, research, grammar, code generation), you must include a disclosure at the beginning of your document stating that AI was used and that you take full responsibility for correctness of the content. You must test every procedure and verify all technical content yourself, as AI frequently produces errors. Do not pass other contributors' existing work through AI tools and resubmit it as a contribution, as this erases the original author's voice. Minor corrections such as typos and broken links do not require disclosure. -## Formatting Guidelines +## Formatting guidelines -### Style Guide +### Style guide -Follow the [Rocky Linux Style Guide](https://docs.rockylinux.org/guides/contribute/style_guide/) for: +Follow the [Rocky Linux style guide](style_guide.md) for: - Grammar and punctuation standards - Voice and tone guidelines @@ -963,9 +947,9 @@ Key points: - Use sentence-style capitalization for headings - Use serial commas ("apples, oranges, and bananas") -### Markdown Formatting +### Markdown formatting -Follow the [Document Formatting Guide](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) for: +Follow the [Document formatting guide](rockydocs_formatting.md) for: - Admonitions (note, warning, tip boxes) - Code blocks @@ -980,7 +964,7 @@ Key rules enforced by our linter: - Avoid trailing whitespace - End files with a single newline -### Code Blocks +### Code blocks Always specify the language for syntax highlighting: @@ -1000,7 +984,7 @@ rocky.example.com ``` ```` -## Validation Checks +## Validation checks Before committing, the pre-commit hooks automatically run: @@ -1010,7 +994,7 @@ Before committing, the pre-commit hooks automatically run: If any check fails, the commit is blocked. Fix the issues and try again. -### Running Checks Manually +### Running checks manually Run all checks: @@ -1031,11 +1015,11 @@ markdownlint docs/ lychee docs/ ``` -### Rocky Docs Contribution Guidelines Validation +### Rocky docs contribution guidelines validation -Beyond the standard checks, your document must comply with the [Rocky Linux Documentation Contribution Guidelines](https://docs.rockylinux.org/guides/contribute/) and [Formatting Standards](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/). Use the following checks to validate your document before submitting a pull request. +Beyond the standard checks, your document must comply with the [Rocky Linux documentation contribution guidelines](beginners.md) and [formatting standards](rockydocs_formatting.md). Use the following checks to validate your document before submitting a pull request. -#### Validate a Single Document +#### Validate a single document Replace `path/to/your-document.md` with your document path in all commands below. @@ -1052,7 +1036,7 @@ markdownlint "path/to/your-document.md" lychee "path/to/your-document.md" --no-progress ``` -#### Metadata Validation +#### Metadata validation Every document requires front matter metadata. Check that your document includes: @@ -1083,7 +1067,7 @@ grep -qE '^tested.*(with|_with|on)?:' path/to/your-document.md && echo "✓ Test grep -q '^tags:' path/to/your-document.md && echo "✓ Tags found" || echo "✗ Missing tags" ``` -#### Heading Structure Validation +#### Heading structure validation Documents should have at most one Level 1 heading (`#`). If your document has `title:` metadata, the title is auto-generated, so you may not need a Level 1 heading at all. @@ -1097,7 +1081,7 @@ else fi ``` -#### Admonition Formatting +#### Admonition formatting Admonitions use the `!!!` syntax with proper types and 4-space indentation for content: @@ -1122,7 +1106,7 @@ else fi ``` -#### Code Block Validation +#### Code block validation Code blocks must specify a language identifier for syntax highlighting: @@ -1144,7 +1128,7 @@ else fi ``` -#### Link Format Validation +#### Link format validation Links should use proper markdown format `[text](url)`. Avoid bare URLs. @@ -1154,7 +1138,7 @@ proper_links=$(grep -oE '\[[^]]+\]\([^)]+\)' path/to/your-document.md 2>/dev/nul echo "ℹ Found $proper_links properly formatted links" ``` -#### Lab Domain Validation +#### Lab domain validation When using example URLs in documentation, use approved domains to pass link validation: @@ -1162,7 +1146,7 @@ When using example URLs in documentation, use approved domains to pass link vali - `home.arpa` - `localhost` or `127.0.0.1` -#### Internal Anchors Warning +#### Internal anchors warning Avoid internal document anchors like `[link](#section-name)` as they may break during translation. @@ -1176,7 +1160,7 @@ else fi ``` -#### Raw HTML Warning +#### Raw HTML warning Avoid using raw HTML elements. Markdown linters flag them and they may not render correctly. The following HTML elements are allowed in `.markdownlint.yml` and will not trigger linting errors: @@ -1193,7 +1177,7 @@ else fi ``` -#### Complete Validation Script +#### Complete validation script Save this script as `validate-doc.sh` and run it against your document: @@ -1332,7 +1316,7 @@ Running lychee... ============================================ ``` -### Adding Words to the Dictionary +### Adding words to the dictionary If the spell checker flags a valid technical term, add it to `.wordlist.txt` in alphabetical order. Common additions include: @@ -1354,9 +1338,9 @@ If you have already staged `.wordlist.txt` by mistake, unstage it before committ git restore --staged .wordlist.txt ``` -## Submitting a Pull Request +## Submitting a pull request -### Pushing Your Changes to the Rocky Linux Documentation Repository +### Pushing your changes to the Rocky Linux documentation repository 1. Sync your fork with upstream: @@ -1387,19 +1371,23 @@ git push origin your-new-document > **Note:** You can also edit existing documentation and push your changes to the Rocky Linux Documentation repository using the same method. -## Getting Help +## Getting help -- **Mattermost**: Join the [Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation) and the community of contributors will be more than happy to help you with your document. +The Rocky Linux community is welcoming and supportive of contributors at all experience levels. Do not hesitate to ask for help. + +- **Mattermost**: Join the [Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation) and the community of contributors will be more than happy to help you with your document - **GitHub Issues**: Report documentation bugs or suggest improvements - **Forums**: Visit the [Rocky Linux Forums](https://forums.rockylinux.org) for general questions -## Additional Resources +If you are unsure where to start, or if something in this guide is unclear, just ask. Someone will point you in the right direction. + +## Additional resources -- [Style Guide](https://docs.rockylinux.org/guides/contribute/style_guide/) - Writing standards -- [Document Formatting](https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/) - Markdown syntax and admonitions -- [Beginner Contributors Guide](https://docs.rockylinux.org/guides/contribute/beginners/) - Detailed walkthrough for new contributors -- [Creating New Documents](https://docs.rockylinux.org/guides/contribute/createnew/) - GitHub-specific instructions -- [Navigation and Structure](https://docs.rockylinux.org/guides/contribute/navigation/) - How the documentation site is organized +- [Style guide](style_guide.md) - Writing standards +- [Document formatting](rockydocs_formatting.md) - Markdown syntax and admonitions +- [Beginner contributors guide](beginners.md) - Detailed walkthrough for new contributors +- [Creating new documents](createnew.md) - GitHub-specific instructions +- [Navigation and structure](navigation.md) - How the documentation site is organized ## License From 978c21a69e55f5978e4e4f8fc79db611b1141b87 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 13:47:48 +0900 Subject: [PATCH 04/14] Update ai_contributors field with correct model identifier Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index 421745b777..a03298e13e 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -2,7 +2,7 @@ title: An expert's guide to contributing author: Howard Van Der Wal contributors: -ai-contributors: Claude Code +ai_contributors: Claude (claude-opus-4-6) tags: - contributing - documentation From 78ef7ced290234559a11622bae6c95859739cc2f Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 13:49:18 +0900 Subject: [PATCH 05/14] Remove reviewing pull requests from welcome sentence Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index a03298e13e..f9334b5e83 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -15,7 +15,7 @@ This document was created with the assistance of AI. All content has been review ## Welcome -Thank you for your interest in contributing to the Rocky Linux documentation. Whether you are writing new guides, translating existing content, editing for clarity, or reviewing pull requests, every contribution matters and is deeply valued by the community. +Thank you for your interest in contributing to the Rocky Linux documentation. Whether you are writing new guides, translating existing content, or editing for clarity, every contribution matters and is deeply valued by the community. This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional.** You do not need any of this to contribute to the Rocky Linux documentation. If you are new to contributing, the [Beginner contributors guide](beginners.md) is a great place to start. You can also edit documentation directly on GitHub without installing anything locally. From a88e67f1e0b5f7e79a2ddbc5b0a114c4f3024e85 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 13:51:17 +0900 Subject: [PATCH 06/14] Update tooling description to recommend for first-time contributors Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index f9334b5e83..16c682f77c 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -17,7 +17,7 @@ This document was created with the assistance of AI. All content has been review Thank you for your interest in contributing to the Rocky Linux documentation. Whether you are writing new guides, translating existing content, or editing for clarity, every contribution matters and is deeply valued by the community. -This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional.** You do not need any of this to contribute to the Rocky Linux documentation. If you are new to contributing, the [Beginner contributors guide](beginners.md) is a great place to start. You can also edit documentation directly on GitHub without installing anything locally. +This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional, but recommended for first-time contributors.** If you are new to contributing, the [Beginner contributors guide](beginners.md) is a great place to start. You can also edit documentation directly on GitHub without installing anything locally. No matter your experience level, the Rocky Linux community is here to help. If you have questions, run into problems, or just want guidance on where to start, reach out on the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). Someone will be happy to help you get started. From a59a2bf9ea9588033111daf02c8cfeba47e25b1e Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 13:55:23 +0900 Subject: [PATCH 07/14] Add evil-mode note to Doom Emacs description Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index 16c682f77c..4bc70d7c22 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -88,7 +88,7 @@ Choose a markdown editor that suits your workflow: #### Terminal editors - [NvChad](https://nvchad.com/) - For Neovim users. See our [NvChad setup guide](../../../books/nvchad/index.md) -- [Doom Emacs](https://github.com/doomemacs/doomemacs) - For Emacs users. Enable the `markdown` module in your config +- [Doom Emacs](https://github.com/doomemacs/doomemacs) - For Emacs users looking for evil-mode. Enable the `markdown` module in your config Terminal editors can integrate the same validation tools used by the pre-commit hooks directly into your editing workflow: From c9b326b54b292f21d27b0a074ebce3129f00412e Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 13:56:52 +0900 Subject: [PATCH 08/14] Change 'reach out on' to 'join' in welcome section Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index 4bc70d7c22..8963c4d215 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -19,7 +19,7 @@ Thank you for your interest in contributing to the Rocky Linux documentation. Wh This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional, but recommended for first-time contributors.** If you are new to contributing, the [Beginner contributors guide](beginners.md) is a great place to start. You can also edit documentation directly on GitHub without installing anything locally. -No matter your experience level, the Rocky Linux community is here to help. If you have questions, run into problems, or just want guidance on where to start, reach out on the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). Someone will be happy to help you get started. +No matter your experience level, the Rocky Linux community is here to help. If you have questions, run into problems, or just want guidance on where to start, join the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). Someone will be happy to help you get started. ## Quick start From 1145e1a18bab1d72627972847f4f1dfce6540e0e Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 14:00:07 +0900 Subject: [PATCH 09/14] Fix preposition in getting help section Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index 8963c4d215..a22ea68f14 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -1373,7 +1373,7 @@ git push origin your-new-document ## Getting help -The Rocky Linux community is welcoming and supportive of contributors at all experience levels. Do not hesitate to ask for help. +The Rocky Linux community is welcoming and supportive of contributors of all experience levels. Do not hesitate to ask for help. - **Mattermost**: Join the [Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation) and the community of contributors will be more than happy to help you with your document - **GitHub Issues**: Report documentation bugs or suggest improvements From afc12f57270462ac2cc868d15b9b954699efca1c Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 14:05:06 +0900 Subject: [PATCH 10/14] Revert title to Contributing to the Rocky Linux Documentation Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index a22ea68f14..1de50c03bd 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -1,5 +1,5 @@ --- -title: An expert's guide to contributing +title: Contributing to the Rocky Linux Documentation author: Howard Van Der Wal contributors: ai_contributors: Claude (claude-opus-4-6) From 9875c4e4dc995f9535934adb755e5c07329366d0 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 14:06:21 +0900 Subject: [PATCH 11/14] Add error reporting note to AI usage disclosure Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index 1de50c03bd..b1eb675e1a 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -11,7 +11,7 @@ tags: ## AI usage disclosure -This document was created with the assistance of AI. All content has been reviewed, tested, and verified by a human author. The author takes full responsibility for the accuracy and correctness of this document. +This document was created with the assistance of AI. All content has been reviewed, tested, and verified by a human author. The author takes full responsibility for the accuracy and correctness of this document. Please report any errors you encounter to the Rocky Linux documentation team. ## Welcome From e61f8ec5fe7214f5e50e2fca198ce4630435a8a3 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 14:07:17 +0900 Subject: [PATCH 12/14] Remove beginner guide reference from welcome section Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index b1eb675e1a..d2c002078e 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -17,7 +17,7 @@ This document was created with the assistance of AI. All content has been review Thank you for your interest in contributing to the Rocky Linux documentation. Whether you are writing new guides, translating existing content, or editing for clarity, every contribution matters and is deeply valued by the community. -This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional, but recommended for first-time contributors.** If you are new to contributing, the [Beginner contributors guide](beginners.md) is a great place to start. You can also edit documentation directly on GitHub without installing anything locally. +This guide is for contributors who want to set up a full local validation environment with spell checking, markdown linting, and link checking tools. **Setting up these tools is entirely optional, but recommended for first-time contributors.** You can also edit documentation directly on GitHub without installing anything locally. No matter your experience level, the Rocky Linux community is here to help. If you have questions, run into problems, or just want guidance on where to start, join the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). Someone will be happy to help you get started. From a4363beecb1f2ce2a41b2e53b479df39a7a34210 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 14:12:20 +0900 Subject: [PATCH 13/14] Add ai_contributors field to front matter example Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index d2c002078e..ddfda25636 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -902,6 +902,7 @@ Every document must include front matter metadata at the top: title: Your Document Title author: Your Name contributors: Comma, Separated, Names +ai_contributors: AI Model (model-version) tested_with: 8.10, 9.7, 10.1 tags: - relevant From 8b9c40b3c592e5c2888004aae799373fa1c6a3c0 Mon Sep 17 00:00:00 2001 From: Howard Van Der Wal Date: Thu, 12 Feb 2026 14:14:21 +0900 Subject: [PATCH 14/14] Move AI usage section above document structure Co-Authored-By: Claude Opus 4.6 --- docs/guides/contribute/expert_contributing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/contribute/expert_contributing.md b/docs/guides/contribute/expert_contributing.md index ddfda25636..6774033a52 100644 --- a/docs/guides/contribute/expert_contributing.md +++ b/docs/guides/contribute/expert_contributing.md @@ -893,6 +893,10 @@ Place your document in the appropriate directory under `docs/guides/`: If your guide does not fit any existing category, place it in the most relevant directory or ask the documentation team in the [Mattermost Documentation channel](https://chat.rockylinux.org/rocky-linux/channels/documentation). +### AI usage + +The Rocky Linux Documentation Team permits AI and LLM tools in the contribution process, following the [Fedora AI Policy](https://docs.fedoraproject.org/en-US/docs/ai-policy/) as a baseline. If you use AI for any part of your documentation (drafting, research, grammar, code generation), you must include a disclosure at the beginning of your document stating that AI was used and that you take full responsibility for correctness of the content. You must test every procedure and verify all technical content yourself, as AI frequently produces errors. Do not pass other contributors' existing work through AI tools and resubmit it as a contribution, as this erases the original author's voice. Minor corrections such as typos and broken links do not require disclosure. + ### Document structure Every document must include front matter metadata at the top: @@ -926,10 +930,6 @@ Feel free to take a look at some example guides to understand the formatting and - [Setting Up libvirt on Rocky Linux](../virtualization/libvirt-rocky.md) - [Automatic template creation with Packer and deployment with Ansible in a VMware vSphere environment](../automation/templates-automation-packer-vsphere.md) -### AI usage - -The Rocky Linux Documentation Team permits AI and LLM tools in the contribution process, following the [Fedora AI Policy](https://docs.fedoraproject.org/en-US/docs/ai-policy/) as a baseline. If you use AI for any part of your documentation (drafting, research, grammar, code generation), you must include a disclosure at the beginning of your document stating that AI was used and that you take full responsibility for correctness of the content. You must test every procedure and verify all technical content yourself, as AI frequently produces errors. Do not pass other contributors' existing work through AI tools and resubmit it as a contribution, as this erases the original author's voice. Minor corrections such as typos and broken links do not require disclosure. - ## Formatting guidelines ### Style guide