The macros in spec-macros.rb and spec-macros/extension.rb are described in the “Vulkan Documentation and Extensions: Procedures and Conventions” document (see the style guide.

Asciidoctor is customized to insert KaTeX <script> tags from math.js for HTML5, and properly pass through math which has \begin{}\/end{} delimiters instead of $$\[\]\(\).

For PDF builds, asciidoctor-mathematical is used to generate images.

khronos.css is the stylesheet used for HTML output. It is a slightly tweaked version of the Asciidoctor 'Colony' theme.

chunkindex contains scripts for building and using a search index for the Vulkan chunked HTML specification.

Asciidoctor requires use of docinfo files to get logos onto the title page, and has very restrictive naming conventions forcing the subdirectories:

• vulkan/docinfo-header.html - Vulkan logo in docinfo HTML form

• vulkansc/docinfo-header.html - Vulkan SC logo in docinfo HTML form

• makedocinfologo - script to convert SVG file to docinfo HTML file

We use a number of Asciidoctor customizations written in Ruby, described briefly below.

• asciidoctor-mathematical-ext.rb - make latexmath: blocks work in table cells

• extension-highlighter.rb - one way of constructing a diff HTML document

• katex_replace.rb - substitute KaTeX for MathJax in output HTML

• loadable_html.rb - add some status messages for slow-loading documents

• rouge-extend-css.rb - override parts of the 'rouge' highlighter CSS

• spec-macros.rb - custom asciidoctor macros used in spec markup

• open_listing_block.rb - allow '----' as a nested open block delimiter when tagged by '[open]'

• vuid-expander.rb - add anchors to valid usage ID tags

• vu-to-json.rb - extract valid usage statements to JSON as part of a spec build

These files are auxiliary data supplied to CI scripts and tools.

• CI/codespell-allowed - words detected by codespell which are allowed in our documents for various reasons

• CI/codespellrc - codespell configuration file

• CI/contractions - disallowed contractions

• CI/contractions-allowed - regular expressions matching filenames allowed to have contractions

• CI/custom-macros - regular expressions matching our custom macros, which are not allowed in non-specification markup that does not use those macros when rendered on e.g. GitHub.

• CI/txt-files-allowed - regular expressions matching externally sourced directories containing, or filenames allowed to end in '.txt'.

• CI/writing - checks for some of the writing guidelines in the style guide.