
a project by JCayouette
Updated
about 1 year
ago.
4 hacker ♥️.
Doc as Code
with Asciidoctor, Jekyll, and TravisCI
Goals: (Subject to change)
- Setup TravisCI to publish doc branches from a product repo to a default build location for continuous version/building
- Lower the barrier for documentation contributors by migrating to Asciidoc as a source format (In place of Docbook XML)
- Use Jekyll for generating the static content + Bootstrap / Foundation or similar
- Begin work on a clear and consistent UX theme
Examples
Markdown Demo
Based on a home hackproject, this will be replaced by Asciidoc and a custom SUSE theme.
- From the demo homepage, select
Available Versions
- Select
SUSE Manager Server 3.1 Stable
- Select
WebUI Reference > Systems > All Systems
- Notice the
Edit me
button at the top of theSystems
page. Click theEdit me
button - You will be redirected to the markdown document in the product github repository
- Login make your changes, and then submit a PR "this is the doc as code process"
- A writer reviews PR and accepts, rejects or requests changes or more info
- If accepted Jekyll rebuilds the site live within 2 minutes
Asciidoc Demo
A very simple starter template.
Under Development Procedure Unavailable:
- Select Available Versions
- Select
SUSE Manager Server 3.1 Stable
- WebUI Reference > Systems > All Systems
- Notice the
Edit me
button at the top of the page. Click theEdit me
button - You will be redirected to the Asciidoc document in the product github repository
- Login, make your changes, and then submit a PR "this is the doc as code process"
- A writer reviews PR and accepts, rejects or requests changes or more info
- If accepted TravisCI rebuilds the site live within a few minutes from the Asciidoc sources
A Few Important Concepts
- Per SUSE product gh-page branches
- Linked to suse.com/documentation as develop/stable dependent upon decision
- Asciidoc converts directly to Docbook xml 4.5 possibly 5
- Writers work only in Asciidoc and convert source of truth documents to docbook for publishing various outputs on suse.com in epub, pdf, and single page html.
- If writers work in Asciidoc alone, then we never need to convert from the opposite direction docbook -> Asciidoc.
- This requires a one time migration for latest docs. (A rather large undertaking, perhaps we can automate some of this with conversion tools)
This project is part of:
Hack Week 16
Activity
Comments
Be the first to comment!
Similar Projects
Investigate if VSCodium can be used as a convenient DocBook editor by tbazant
Project Description & Goal for this Hackweek...
Port the Minion job queue to TypeScript by kraih
Project Description
As part of the [mojo....
chatterbox by gbaccini
Project Description
[chatterbox](https://...
Improve OpenSCAP support in Uyuni by admehmood
[comment]: # (Please use the project descriptio...
Add xterm.js to D-Installer web interface by IGonzalezSosa
Project Description
Having a terminal you...
Uyuni test suite improvements by dgedon
Project Description
Uyuni is the upstream...
Simple time scale for active record models by digitaltomm
[comment]: # (Please use the project descriptio...