- CSS 52.6%
- HTML 47.4%
Justin Wheeler
03344e3259
Replace the original AsciiBinder build instructions with a document that tells the story of this repository's place in the Fedora Docs platform evolution, from Docbook/Publican to AsciiBinder to Antora. Credit Brian Exelbierd (bex) for creating this repo during his tenure as Fedora Community Architect (2016-2019). Add LICENSE.txt to make the repository's license explicit. The content was implicitly licensed before under the Fedora Project Contributor Agreement, but lacked an actual license file. The repository is being archived because: - It contains only scaffolding with no content ever written - The AsciiBinder tooling it was built for was superseded by Antora - Its value is as a historical artifact, not as a living project - Preserving it read-only prevents well-meaning but unnecessary conversion attempts Includes a guided tour of each file, a timeline of the platform transition, and links to current Fedora Docs resources. Assisted-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Justin Wheeler <jwheel@redhat.com> |
||
|---|---|---|
| _images | ||
| _javascripts | ||
| _stylesheets | ||
| _templates | ||
| .gitignore | ||
| _distro_map.yml | ||
| _topic_map.yml | ||
| AGENTS.md | ||
| index-main.html | ||
| LICENSE.txt | ||
| README.md | ||
Fedora Contribution Howto (Archived)
This repository is archived and no longer actively maintained. It is preserved as a historical artifact from the Fedora Docs platform transition.
Historical Context
For many years, Fedora documentation was built with Docbook and Publican. While reliable, Docbook's XML syntax was a barrier to contribution and the tooling was showing its age.
Around 2017, the Fedora Docs Team began exploring AsciiDoc as a lighter-weight replacement. This repository is one of the earliest experiments from that effort, using AsciiBinder as the build tool. AsciiBinder was an Open Source framework (originally developed for OpenShift documentation) that compiled AsciiDoc sources into a multi-version documentation site.
This particular repo was put together by Brian Exelbierd (bex) during his tenure as Fedora Community Architect (2016--2019). It set up the scaffolding for a "Fedora Contribution Howto" guide but was never populated with content. It represents the exploratory phase where the team was evaluating tooling and workflows before committing to a platform.
By March 2018, the Fedora Docs Team had launched the new documentation site at docs.fedoraproject.org built on Antora, a purpose-built static site generator for AsciiDoc documentation. The experimentation with AsciiBinder, including this repo, helped inform that decision and contributed to the development of the Fedora Antora theme and site infrastructure.
Timeline
| Period | Event |
|---|---|
| Pre-2018 | Fedora Docs built with Docbook and Publican |
| ~2017 | Exploration of AsciiDoc and AsciiBinder as replacements; this repo created by Brian Exelbierd (bex) |
| March 2018 | Official launch of Antora-based Fedora Docs site |
| Today | Fedora Docs runs entirely on Antora |
What's in This Repo
This repo contains only AsciiBinder scaffolding with no AsciiDoc content. The topic files declared in the configuration were never created.
| File/Directory | Purpose |
|---|---|
_distro_map.yml |
Distribution and branch mapping (maps master branch to the "fedora" distro) |
_topic_map.yml |
Content hierarchy declaration (references .adoc files under en-US/ that don't exist) |
_templates/ |
ERB page templates for AsciiBinder rendering (layout, navigation, CSS loading) |
_images/ |
Static image assets (Fedora and Red Hat branding) |
_stylesheets/ |
CSS stylesheets for the AsciiBinder site |
_javascripts/ |
JavaScript assets (Bootstrap offcanvas navigation) |
index-main.html |
Bootstrap 3 landing page for the documentation site |
Where to Go Instead
- Fedora Docs: docs.fedoraproject.org -- the current documentation site
- Fedora Docs Template: fedora-docs-template -- the canonical starting point for new Antora documentation components
- Antora Documentation: docs.antora.org -- learn how Antora works
- AsciiDoc Language: docs.asciidoctor.org -- AsciiDoc syntax and language reference
Archiving
This repository is recommended to be archived (set to read-only) on Forge. The scaffolding is preserved intact as a historical reference and should not be modified.