
a project by JCayouette
Updated
almost 2 years
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
Adapt Bootstrap code in OBS to support theming by enavarro_suse
Project Description
After the release of ...
Bring up-to-date daps infrastructure to Debian/Ubuntu distributions by tbazant
Project Description
daps (https://opensu...
Implement a self-servicable Trello replacement in Jira by jplack
[comment]: # (Please use the project descriptio...
Reduce the amount of TODOs for RuboCop in OBS by enavarro_suse
Project Description
The OBS project has a...
Catalog/Online Store for a bakery in Rails 7 by gfilippetti
[comment]: # (Please use the project descriptio...
Dawnscanner: parsing a simple sinatra application by pperego
[comment]: # (Please use the project descriptio...
Modernize SCC Customer Management and/or Patchfinder by digitaltomm
[comment]: # (Please use the project descriptio...