{"id":43170369,"url":"https://github.com/rocky-linux/docs.rockylinux.org","last_synced_at":"2026-02-01T02:20:30.412Z","repository":{"id":37941273,"uuid":"333151333","full_name":"rocky-linux/docs.rockylinux.org","owner":"rocky-linux","description":"The Rocky Linux documentation site, built with \u0026 powered by MkDocs","archived":false,"fork":false,"pushed_at":"2026-01-26T05:59:22.000Z","size":5416,"stargazers_count":21,"open_issues_count":5,"forks_count":14,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-26T19:28:00.055Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.rockylinux.org","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-sa-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rocky-linux.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-01-26T16:49:08.000Z","updated_at":"2026-01-26T05:59:25.000Z","dependencies_parsed_at":"2024-02-09T23:26:02.397Z","dependency_job_id":"387701ee-bdc4-481c-9917-b0ce0cd7d1d5","html_url":"https://github.com/rocky-linux/docs.rockylinux.org","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rocky-linux/docs.rockylinux.org","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocky-linux%2Fdocs.rockylinux.org","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocky-linux%2Fdocs.rockylinux.org/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocky-linux%2Fdocs.rockylinux.org/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocky-linux%2Fdocs.rockylinux.org/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rocky-linux","download_url":"https://codeload.github.com/rocky-linux/docs.rockylinux.org/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rocky-linux%2Fdocs.rockylinux.org/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28965144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T02:14:24.993Z","status":"ssl_error","status_checked_at":"2026-02-01T02:13:55.706Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-01T02:20:29.781Z","updated_at":"2026-02-01T02:20:30.407Z","avatar_url":"https://github.com/rocky-linux.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docs.rockylinux.org\n\n## Overview\n\nThis repository is responsible for building and deploying the official Rocky Linux documentation site, hosted at [docs.rockylinux.org](https://docs.rockylinux.org). The site is built and deployed automatically via the [Vercel](https://vercel.com/) platform.\n\n\u003e [!IMPORTANT]\n\u003e This repository contains the *build and deployment logic only*. It does not contain the documentation content itself.\n\n## Table of Contents\n- [Content Source ](#content-source)\n- [How the Build Process Works](#how-the-build-process-works)\n- [Key Files \u0026 Scripts](#key-files--scripts)\n- [Deep Dive: The `vercel-build.sh` Script](#deep-dive-the-vercel-buildsh-script)\n- [How to Maintain the Site](#how-to-maintain-the-site)\n- [Managing Deployments on Vercel](#managing-deployments-on-vercel)\n  - [Vercel CLI](#vercel-cli)\n  - [Vercel Web UI](#vercel-web-ui)\n- [Local Development \u0026 Testing](#local-development--testing)\n\n## Content Source\n\nAll documentation content is sourced from the [rocky-linux/documentation](https://github.com/rocky-linux/documentation) GitHub repository. The build script in this repository clones the content repo during the Vercel deployment process.\n\n## How the Build Process Works\n\nThe deployment process is orchestrated by Vercel, which executes a custom build script.\n\n1.  **Trigger:** A push to this repository's `main` branch triggers a new build on Vercel.\n2.  **Build:** Vercel runs the `./scripts/vercel-build.sh` script, which uses [mkdocs](https://www.mkdocs.org/) and the [mike](https://github.com/jimporter/mike) plugin to build a versioned static HTML site.\n3.  **Deploy:** The script places the final generated site into the `site/` directory, which Vercel then deploys to production.\n4.  **URL Structure:** The site uses a \"Root + Versioned\" deployment strategy. The latest documentation (currently Rocky Linux 10) is served from the root URL (`/`), while all documentation versions remain accessible via versioned paths (e.g., `/8/`, `/9/`, `/latest/`).\n\n## Key Files \u0026 Scripts\n\n-   `vercel.json`: Configures Vercel to use the custom build command and specifies the output directory (`site`).\n-   `scripts/vercel-build.sh`: The primary script that orchestrates the entire build. It contains all the logic for cloning, versioning, and building the documentation.\n-   `requirements.txt`: A standard Python file listing the dependencies required for the build, such as `mkdocs` and `mike`.\n-   `mkdocs.yml`: The main configuration file for `mkdocs`. The build script manages which configuration is used for the build.\n\n## Deep Dive: The `vercel-build.sh` Script\n\nThis script is the heart of the repository and is designed to run within the Vercel environment. For maintainers, understanding its structure is key.\n\n#### Stage 1: Initialization\nThe script begins by installing Python dependencies from `requirements.txt`. It also creates a small `mkdocs` executable wrapper script. This ensures that `mike` can find and use the correct `mkdocs` instance within the Vercel build environment's `PATH`.\n\n#### Stage 2: The `build_version` Function\nThis function is called for each documentation version that needs to be built. It:\n1.  Clones a specific branch (e.g., `rocky-8`) from the `rocky-linux/documentation` repository.\n2.  Crucially, it performs a full clone to preserve the entire git history. This is required for the `git-revision-date-localized-plugin` to accurately display when a page was last updated.\n3.  It uses symlinks to make the cloned content available to `mike` while preserving the git context.\n\n#### Stage 3: Building with `mike`\nAfter cloning a version, the script uses `mike deploy` to build the static HTML for that version. `mike` manages the versioning by committing the built site to a temporary `gh-pages` branch within the build environment. This process is repeated for all specified versions.\n\n#### Stage 4: Site Extraction\nOnce `mike` has built all versions into the `gh-pages` branch, the script extracts the complete static site into the `site/` directory using `git archive`. This directory is the final artifact that Vercel will deploy.\n\n#### Stage 5: Root Deployment\nTo ensure `docs.rockylinux.org` serves the latest documentation directly, the script performs a final step: it copies all content from the `site/latest/` directory to the root of the `site/` directory. It carefully preserves the `versions.json` file to ensure the version-switching dropdown menu continues to function correctly across the entire site.\n\n## How to Maintain the Site\n\nMaintenance typically involves modifying the build script to add, update, or remove documentation versions.\n\n#### Adding a New Documentation Version\n1.  Open `scripts/vercel-build.sh`.\n2.  Find the section where `build_version` is called.\n3.  Add a new line for the new version, specifying the version number and the corresponding branch name from the content repository. For example, to add Rocky Linux 11 from the `rocky-11` branch:\n    ```bash\n    build_version \"11\" \"rocky-11\" \"\" \"\"\n    ```\n\n#### Changing the Default Version\nThe default version is the one aliased to `latest`.\n1.  Open `scripts/vercel-build.sh`.\n2.  Modify the `build_version` call that includes `\"latest\"` as the alias. For example, to make version 11 the new latest:\n    ```bash\n    # Old\n    build_version \"10\" \"main\" \"latest\" \"\"\n\n    # New\n    build_version \"11\" \"rocky-11\" \"latest\" \"\"\n    ```\n3.  The `mike set-default` command uses `latest`, so it does not need to be changed.\n\n#### Removing an Old Version\n1.  Open `scripts/vercel-build.sh`.\n2.  Find the `build_version` call for the version you want to remove and delete or comment out the line.\n\n## Managing Deployments on Vercel\n\nDeployments are handled automatically by Vercel when commits are pushed to the `main` branch. However, maintainers can also manage deployments manually via the Vercel CLI or the web dashboard.\n\n### Vercel CLI\n\nFor more direct control, the Vercel CLI is a powerful tool. It allows you to deploy, manage, and inspect your project from the command line.\n\n#### 1. Installation\nFirst, install the Vercel CLI globally using `npm` (Node.js is required):\n```shell\nnpm i -g vercel\n```\n\n#### 2. Login\nLog in to your Vercel account. This will likely open a browser window for authentication.\n```shell\nvercel login\n```\n\n#### 3. Linking the Project\nBefore you can manage a project, you must link your local directory to the remote Vercel project. This is a crucial one-time step.\n\n```shell\n# Clone the repository if you haven't already\ngit clone https://github.com/rocky-linux/docs.rockylinux.org.git\ncd docs.rockylinux.org\n\n# Link the project\nvercel link\n```\nThe CLI will interactively guide you to select the correct Vercel scope (team) and project.\n\nFor non-interactive environments or to be explicit, you can use flags:\n```shell\n# Example of linking to a specific project within a specific scope (team)\nvercel link --scope=rocky-linux-scope --project=docs-rockylinux-org\n```\n\u003e [!NOTE]\n\u003e Replace `rocky-linux-scope` and `docs-rockylinux-org` with the actual scope and project names on Vercel.\n\n#### 4. Triggering Manual Deployments\nYou can trigger new builds and deployments directly from your local machine. This is useful for testing changes in a preview environment before merging to `main`.\n\n-   **Preview Deployment:** Create a unique preview deployment with its own URL. Vercel builds the project and provides a link to the result.\n    ```shell\n    vercel\n    ```\n-   **Production Deployment:** Push a new build to the official production domain (`docs.rockylinux.org`).\n    ```shell\n    vercel --prod\n    ```\n    \u003e [!WARNING]\n\u003e This command updates the live site. It should only be used when you are certain the build is stable.\n\n#### 5. Inspecting Deployments \u0026 Logs\n-   **List Projects:** To see all projects you have access to:\n    ```shell\n    vercel project ls\n    ```\n-   **List Deployments:** To see a list of recent deployments for the linked project:\n    ```shell\n    vercel ls\n    ```\n-   **View Logs:** To view the build or runtime logs for a specific deployment in real-time, use the deployment URL provided by the `vercel` or `vercel ls` commands:\n    ```shell\n    vercel logs \u003cdeployment-url\u003e\n    ```\n\n#### 6. CLI Troubleshooting\n-   **Authentication Issues:** If you get permission errors, run `vercel login` again to re-authenticate.\n-   **Wrong Project/Scope:** If commands are failing or not showing the right information, you may be linked to the wrong project. Run `vercel link` again to re-link your local directory. You can check the current link status by inspecting the `.vercel` directory.\n-   **Build Failures:** If a manual deployment with `vercel` fails, the command will output a URL to the build logs for you to inspect.\n\n### Vercel Web UI\n\nThe [Vercel Dashboard](https://vercel.com/) provides a user-friendly web interface for project management. After logging in and selecting the project, you can perform several key actions:\n\n-   **Viewing Deployments:**\n    1.  Navigate to the project's dashboard.\n    2.  Click the **Deployments** tab.\n    3.  Here you will see a complete history of all deployments (both production and preview), along with their status, branch, and commit message.\n\n-   **Inspecting Logs:**\n    1.  From the **Deployments** list, click on a specific deployment.\n    2.  Select the **Build Logs** or **Functions** tab to view detailed logs. This is essential for diagnosing a failed build.\n\n-   **Promoting to Production:**\n    You can manually promote a successful preview deployment to production without needing a new build.\n    1.  Find the desired preview deployment in the **Deployments** list.\n    2.  Click the overflow menu (three dots) on the right.\n    3.  Select **Promote to Production**.\n\n-   **Managing Domains and Settings:**\n    -   **Domains:** Use the **Settings -\u003e Domains** tab to manage custom domains and subdomains.\n    -   **Environment Variables:** Use the **Settings -\u003e Environment Variables** tab to add, edit, or remove any necessary variables for the build environment.\n\n## Local Development \u0026 Testing\n\nYou can simulate the Vercel build process locally to test changes.\n1.  Ensure you have Python 3 and `pip` installed.\n2.  Install the required dependencies:\n    ```shell\n    pip3 install -r requirements.txt\n    ```\n3.  Run the build script:\n    ```shell\n    ./scripts/vercel-build.sh\n    ```\n4.  The script will execute the full build process and place the output in the `site/` directory. You can inspect the contents or serve them locally with a simple web server to verify your changes.\n    ```shell\n    python3 -m http.server --directory site\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocky-linux%2Fdocs.rockylinux.org","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frocky-linux%2Fdocs.rockylinux.org","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frocky-linux%2Fdocs.rockylinux.org/lists"}