Skip to content

CONTRIBUTING.adoc

Latest commit

 

History

History
83 lines (64 loc) · 2.47 KB

CONTRIBUTING.adoc

File metadata and controls

83 lines (64 loc) · 2.47 KB

Vulkan Guide Contributing

While open for contributions from all, there are a few contribution rules in place.

The main design goal for the Vulkan Guide is to be “lean” and prevent any duplication of information. When possible the Vulkan Guide should guide a user to another resource via a hyperlink.

Repo Structure

  • README.adoc is the landing page if viewing from github

  • antora/modules/ROOT/pages/index.adoc is the landing page if viewing from docs.vulkan.org

Adding a new chapter

When adding a new chapter, make sure to add the .adoc to both README.adoc and antora/modules/ROOT/nav.adoc

Markup

The Guide was converted from Markdown to Asciidoc markup format in the past.

We have added support for the Antora site generator under the antora/ directory. See https://github.com/KhronosGroup/Vulkan-Site for details and links to a site incorporating the Vulkan specification, proposals, and this guide.

When adding new chapters, or adding cross-references to existing chapters, it’s necessary to take these steps:

  1. Links to new chapters must be added at the appropriate place in README.adoc and the corresponding place in antora/modules/ROOT/nav.adoc, using the existing conventions of each file.

  2. For each chapter chapters/page.adoc which contains internal cross-references, add this boilerplate at the top of the document:

    ifndef::chapters[:chapters:]

    or, for chapters chapters/extensions/page.adoc, add this boilerplate:

    ifndef::chapters[:chapters: ../]

  3. When creating an internal cross-reference link to chapters/page.adoc, mark it up as follows:

    This is a xref:{chapters}page.adoc#anchor[cross-reference]

    If cross-referencing chapters/extensions/page.adoc, mark it up as follows:

    This is a xref:{chapters}/extensions/page.adoc#anchor[cross-reference]

  4. The anchor is arbitrary, but is not optional. While asciidoctor will generate anchor names automatically based on section titles, for link stability it is best to use an explicit anchor on the title of the target file:

    ifndef::chapters[:chapters:]

[[anchor]]
= Target Page

Together, these steps allow cross-references to resolve correctly whether viewing the Guide as a single document, or a set of related pages.