fedora-coreos-docs
fedora-coreos-docs copied to clipboard
coreos
Providing alternative examples
There is an open PR (#171) and a couple of merged PRs (#543, #213) that deal with alternative examples / example environment different from the default Linux one.
Additionally, tooling for FCOS is available on Linux, macOS, and Windows each with their own idiosyncrasies and caveats. I am wondering whether it makes sense to … streamline the documentation here a little and use e.g. asciidoctor-tabs to provide "standard" means to offer examples for different platforms & environments?
That looks like a good idea. However the Fedora CoreOS documentation is built and hosted on Fedora Infrastructure and I don't know if we have this extension available there.
I think it should be technically possible to include the extension directly via the existing playbook by adding an extensions list with the value '@asciidoctor/tabs'`. That assumes the actual build process has access to the internet (which it should because you source the UI from gitlab.com).
However, the "fun" part is then having to dynamically rewrite and include so called supplemental files. I can totally see why you wouldn't want to do that and instead rely on a neatly packaged and complete base UI package styled in the official Fedora design. Including the extension "out of turn" effectively makes the CoreOS documentation brittle and unnecessarily hard to maintain.
I suppose this would then be a base line issue (+ PR) over at Fedora Docs Website in the Fedora Doc UI repository? Once official support for this exists only the extension would have to be included as "we use this"-declaration without having to worry about breaking styling.
Yes, if you can bring that up with the docs team there that would be great as they likely have more info about the build process and how this is set up overall.
Just as a heads-up here. I believe this should best be tackled after Fedora Docs' site CSS breaks many AsciiDoctor features has been resolved.
Dusty asked about this at https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/issues/12
This has been deployed in the Fedora infra, so we should be able to use it now: https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/issues/12