AsciiDocsy is designed by a technical documentation specialist who builds bespoke AsciiDoc platforms for world-class enterprises.
[.case]*_On the front end_*, AsciiDocsy [.buz]_delivers_.
Designed to meet the technical documentation deployment needs of full-scale, multi-product software companies, AsciiDocsy remains fully aware that all such enterprises start small and still need world-class docs.
[.case]*_On the back end_*, AsciiDocsy [.buz]_unifies_.
The codebase brings together developers and technical writers, allowing the latter to achieve momentous feats in collaboration with the developers whose work they document.Configuring Inline Semantics
AsciiDocsy enables robust use of inline semantics, as documented in the Inline Semantics Style Guide.
There are a few ways you can customize these semantics, both meaning and presentation.
The default semantic roles AsciiDocsy provides — term, cite, path, cmd, and so forth — is relatively arbitrary. Some I have seen or used in production, others (like case) are more experimental.
These are not coded into the theme in any way except with CSS. Simply do not use any role you do not wish to. You may also add your own or alter the existing roles however you prefer.
Use your custom.css file to modify the rendered presentation, and use your own style policy to alter the source markup (the quote characters).
Which quotes are used to contain your text (backtick, underscore, aserisk, or hash) will determine the fallback styling for any rendering not styled by your semantic CSS, such as Asciidoctor PDF output with no styling designated for the roles.
Role class definitions are not attached to the specific HTML elements used by Asciidoctor.
This means for other roles, you can swap the quote characters in order to affect the rendered formatting with italics (underscore), bold (asterisk), or no styling (hash symbol).
You can even use a combination of bold and italic as quotes: *_bold and italic_*.
| Do not make more semantic roles than your authors will use properly, and do not use them so frequently that they make the page too busy or awkward. Remove any roles that are not in regular use. |
Inline Semantics in Action
Take for example the AsciiDocsy “Purpose” section of the README, which is included for rendering in the topic template _docs/topics/theme_intro.adoc.
Purpose section of
README.adocThis code renders like so in the AsciiDocsy theme:
Without the AsciiDocsy theme — such as in unthemed PDF or on GitHub — styling “degrades” gracefully, falling back on formatting designated by the quotes syntax.
In this case, the terms marked with the case role are bold and italic on GitHub, whereas the term marked buz is italic on GitHub even though it is unitalicized in AsciiDocsy.