Framework for adding refpages to docs.vulkan.org (#2553)

* Framework for adding refpages to docs.vulkan.org

Runs the same refpage extraction step, but sourced from the rewritten
spec sources in the Antora spec component, and output to a new refpages
component.
Still need to:

* Generate refpages nav.adoc from refpage list (ideally with some structure)
* Set attributes in refpages antora.yml to refer to the spec component for partials and images
* Rewrite xrefs relative to the spec component, instead of as links into the registry HTML spec (changes to genRef.py needed)

* Add partials / images directories for refpages module and add cross-file-links attribute when building it

* Setup document attributes in refpages module so custom macros know to
link to other refpages, not to the specification.

* checkpoit

* Add module prefix (if specified) during Antora markup conversion

* Refactor parameter passing to collect needed global variables for
xref rewrites, since they need to be passed several levels deep.
Move importFileModule to reflib.py for reuse by several scripts.
Consistently pass around the full path to pageMap.py and xrefMap.py, not
just the directory they're located in.

* Rewrite links correctly for Antora in scripts/genRef.py.
Use more consistent option / variable naming and capitalization when referring to maps.
Pass spec module name correctly when building Antora refpage sources.

* Generate Antora nav.adoc as part of refpages.
This is incomplete - aliases are not included because they are part of the same
page as the API they alias.
Also, extension refpages are not included yet.

* Improve nav.adoc generation.
Remove old apispec.adoc generated file and corresponding Makefile
targets 'manhtml' and 'manpdf', and use a different proxy target when
generating the refpage .adoc markup.

* Remove single page (apispec.adoc) target completely from genRef.py.
Improve refpage nav.adoc generation.
Still needs to handle pages in refpage_other_types and perhaps aliases
need to be handled differently, but much closer.

* Rename the array holding refpage details to 'refpageMap' to distinguish
it from the 'pageMap' of asciidoc anchors to specification filenames.

Use more consistent f'' style for strings with imbedded variables.

* Update Antora nav generation in genRef.py, and remove old HTML TOC
generation, which was never published.
Now includes nav links for aliases which link to the aliased page.
Minor fixes to refpage block markup.
Split diagnostics from warnings in refpage generation log.

Still problematic:

* Generated interface files (e.g. refpage.<extensionname>.adoc) for promoted extensions are not resolving e.g. slink: markup for APIs which are aliased to promoted APIs.
* nav index is very long (3100 lines!) and while it does collapse at the level of first letters, it does not collapse at the level of refpage types (e.g. 'Structures', 'API Core Versions', etc.)

Otherwise this is looking much better.

* Fix typo.

* Minor markup cleanup to proposals to properly link to the specification,
reducing complaints from Antora about unresolved xrefs, and otherwise
improve markup consistency.

* Improve handling of aliases in refpage generation and minor markup fixes.

* Minor markup cleanup

Author: oddhack

Makefile

@@ -1,5 +1,4 @@
 # Copyright 2014-2025 The Khronos Group Inc.
-#
 # SPDX-License-Identifier: Apache-2.0
 
 # Vulkan Specification makefile
@@ -410,7 +409,7 @@ $(VUDIR)/validusage.json: $(SPECSRC) $(COMMONDOCS) $(PYXREFMAP) $(PYPAGEMAP)
 	$(QUIET)$(ASCIIDOC) $(ADOCOPTS) $(ADOCVUOPTS) --trace \
 	    -a json_output=$@ -o $@ $(SPECSRC)
 	$(QUIET)$(PYTHON) $(SCRIPTS)/add_validusage_pages.py \
-	    -xrefmap $(PYXREFMAP) -pagemap $(PYPAGEMAP) -validusage $@
+	    -xrefMap $(PYXREFMAP) -pageMap $(PYPAGEMAP) -validusage $@
 
 # Vulkan Documentation and Extensions, a.k.a. "Style Guide" documentation
 
@@ -597,7 +596,7 @@ check-xrefs: $(HTMLDIR)/vkspec.html
 	$(PYTHON) $(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html
 
 # Generated refpage sources. For now, always build all refpages.
-MANSOURCES   = $(filter-out $(REFPATH)/apispec.adoc, $(wildcard $(REFPATH)/*.adoc))
+MANSOURCES   = $(wildcard $(REFPATH)/*.adoc)
 
 # Generation of refpage asciidoctor sources by extraction from the
 # specification(s).
@@ -609,25 +608,30 @@ MANSOURCES   = $(filter-out $(REFPATH)/apispec.adoc, $(wildcard $(REFPATH)/*.ado
 # Should pass in $(EXTOPTIONS) to determine which pages to generate.
 # For now, all core and extension refpages are extracted by genRef.py.
 GENREF = $(SCRIPTS)/genRef.py
-LOGFILE = $(REFPATH)/refpage.log
-refpages: $(REFPATH)/apispec.adoc
-$(REFPATH)/apispec.adoc: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(PYAPIMAP)
+LOGPATH = $(REFPATH)/
+# Proxy target for the entire set of generated refpages.
+# This page will always be generated.
+REFPAGEPROXY = $(REFPATH)/VkResult.adoc
+refpages: $(REFPAGEPROXY)
+$(REFPAGEPROXY): $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(PYAPIMAP)
 	$(QUIET)$(MKDIR) $(REFPATH)
 	$(PYTHON) $(GENREF) -genpath $(GENERATED) -basedir $(REFPATH) \
-	    -log $(LOGFILE) -extpath $(SPECDIR)/appendices \
+	    -diag $(LOGPATH)/refpage.diag \
+	    -warn $(LOGPATH)/refpage.warn \
+	    -extpath $(SPECDIR)/appendices \
 	    $(EXTOPTIONS) $(SPECFILES)
 
 # These targets are HTML5 refpages
 #
-# The recursive $(MAKE) is an apparently unavoidable hack, since the
-# actual list of man page sources is not known until after
-# $(REFPATH)/apispec.adoc is generated. $(GENDEPENDS) is generated before
-# running the recursive make, so it does not trigger twice
+# The recursive $(MAKE) is an apparently unavoidable hack, since the list
+# of refpage sources is not known until $(REFPAGEPROXY) is generated.
+# $(GENDEPENDS) is generated before the recursive make, so it does not
+# trigger twice.
 # $(SUBMAKEOPTIONS) suppresses the redundant "Entering / leaving"
 # messages make normally prints out, similarly to suppressing make
 # command output logging in the individual refpage actions below.
 SUBMAKEOPTIONS = --no-print-directory
-manhtmlpages: $(REFPATH)/apispec.adoc $(GENDEPENDS)
+manhtmlpages: $(REFPAGEPROXY) $(GENDEPENDS)
 	$(QUIET) echo "manhtmlpages: building HTML refpages with these options:"
 	$(QUIET) echo $(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) \
 	    $(ADOCREFOPTS) -d manpage -o REFPAGE.html REFPAGE.adoc
@@ -665,32 +669,6 @@ $(MANHTMLDIR)/%.html: $(REFPATH)/%.adoc $(GENDEPENDS) $(KATEXINSTDIR)
 	    $(TRANSLATEMATH) $@ ; \
 	fi
 
-# The 'manhtml' and 'manpdf' targets are NO LONGER SUPPORTED by Khronos.
-# They generate HTML5 and PDF single-file versions of the refpages.
-# The generated refpage sources are included by $(REFPATH)/apispec.adoc,
-# and are always generated along with that file. Therefore there is no
-# need for a recursive $(MAKE) or a $(MANHTML) dependency, unlike the
-# manhtmlpages target.
-
-manpdf: $(OUTDIR)/apispec.pdf
-
-$(OUTDIR)/apispec.pdf: $(SPECVERSION) $(REFPATH)/apispec.adoc $(SVGFILES) $(GENDEPENDS)
-	$(QUIET)$(MKDIR) $(OUTDIR)
-	$(QUIET)$(MKDIR) $(PDFMATHDIR)
-	$(QUIET)$(ASCIIDOC) -b pdf -a html_spec_relative='html/vkspec.html' \
-	    $(ADOCOPTS) $(ADOCPDFOPTS) -o $@ $(REFPATH)/apispec.adoc
-	$(QUIET)$(OPTIMIZEPDF) $@ $@.out.pdf && mv $@.out.pdf $@
-
-manhtml: $(OUTDIR)/apispec.html
-
-$(OUTDIR)/apispec.html: KATEXDIR = katex
-$(OUTDIR)/apispec.html: ADOCMISCOPTS =
-$(OUTDIR)/apispec.html: $(SPECVERSION) $(REFPATH)/apispec.adoc $(SVGFILES) $(GENDEPENDS) $(KATEXINSTDIR)
-	$(QUIET)$(MKDIR) $(OUTDIR)
-	$(QUIET)$(ASCIIDOC) -b html5 -a html_spec_relative='html/vkspec.html' \
-	    $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ $(REFPATH)/apispec.adoc
-	$(QUIET)$(TRANSLATEMATH) $@
-
 # Create links for refpage aliases
 
 MAKEMANALIASES = $(SCRIPTS)/makemanaliases.py
@@ -741,7 +719,7 @@ rubyapi $(RBAPIMAP): $(VKXML) $(GENVK)
 # Cross-references of anchors to spec chapters they lie within
 # Used both by Antora and validusage_page targets
 
-xrefmaps: $(PYXREFMAP) $(JSXREFMAP)
+xrefMap: $(PYXREFMAP) $(JSXREFMAP)
 
 $(PYXREFMAP) $(JSXREFMAP): $(HTMLDIR)/vkspec.html
 	$(QUIET)$(PYTHON) $(SCRIPTS)/map_html_anchors.py \
@@ -811,17 +789,17 @@ $(SYNCDEPEND): $(VKXML) $(GENVK)
 # After the targets are built, the $(JSXREFMAP) and $(JSPAGEMAP) files
 # used by spec macros in the Antora build must be copied into the Antora
 # project build tree, which is in a different repository.
-setup_antora: xrefmaps .WAIT setup_spec_antora setup_features_antora
+setup_antora: xrefMap .WAIT setup_spec_antora setup_features_antora setup_refpages_antora
 
 # Generate Antora spec module content by rewriting spec sources
 # Individual files must be specified last
-# This target is also used to generate the pagemap, which is combined
-# with the xrefmaps above to map VUID anchors into the Antora pages they
+# This target is also used to generate the pageMap, which is combined
+# with the xrefMap above to map VUID anchors into the Antora pages they
 # are found within.
 
 ANTORA_SPECMODULE = antora/spec/modules/ROOT
 
-# The list of files is long enough to exceed system limits on arguments
+# The list of files is long enough to exceed system limits on argument
 # lists, so instead of passing them on the command line they are stored
 # in a separate file.
 ANTORA_FILELIST = $(GENERATED)/antoraFileList.txt
@@ -835,15 +813,16 @@ ANTORA_EXTRAFILES = \
 	$(JSXREFMAP) \
 	$(JSAPIMAP)
 
-# The pagemap is copied, separately since the rewrite script creates it.
-setup_spec_antora pagemap $(JSPAGEMAP) $(PYPAGEMAP): xrefmaps $(JSAPIMAP)
+# The pageMap is copied, separately since antora-prep.py creates it.
+setup_spec_antora pageMap $(JSPAGEMAP) $(PYPAGEMAP): xrefMap $(JSAPIMAP)
 	$(QUIET)find $(GENERATED) ./chapters ./appendices -name '[A-Za-z]*.adoc' | \
 	    grep -v /vulkanscdeviations.adoc > $(ANTORA_FILELIST)
 	$(QUIET)ls -1 $(ANTORA_EXTRAFILES) >> $(ANTORA_FILELIST)
 	$(QUIET)$(PYTHON) $(SCRIPTS)/antora-prep.py \
 	    -root . \
 	    -component $(shell realpath antora/spec/modules/ROOT) \
-	    -xrefpath $(GENERATED) \
+	    -xrefMap $(PYXREFMAP) \
+	    -module 'spec::' \
 	    -pageHeaders antora/pageHeaders-spec.adoc \
 	    -jspagemap $(JSPAGEMAP) \
 	    -pypagemap $(PYPAGEMAP) \
@@ -852,11 +831,11 @@ setup_spec_antora pagemap $(JSPAGEMAP) $(PYPAGEMAP): xrefmaps $(JSAPIMAP)
 
 # Generate Antora features module content by rewriting feature sources
 # No additional pageHeaders required.
-setup_features_antora: xrefmaps features_nav_antora
+setup_features_antora: xrefMap features_nav_antora
 	$(QUIET)$(PYTHON) $(SCRIPTS)/antora-prep.py \
 	    -root . \
 	    -component $(shell realpath antora/features/modules/features) \
-	    -xrefpath $(GENERATED) \
+	    -xrefMap $(PYXREFMAP) \
 	    `find ./images/proposals -type f` \
 	    `find ./proposals -name '[A-Za-z]*.adoc'`
 
@@ -875,6 +854,37 @@ features_nav_antora:
 	    -roadmappath proposals/Roadmap.adoc \
 	    `find ./proposals -name 'VK_*.adoc'`
 
+# Generate Antora refpages module content by extraction from rewritten
+# spec sources.
+# The sources in the spec component partials/ directory are used since
+# that has all source files, and some of the files not in pages/ have
+# refpage content.
+# At present, this is done by symlinking spec module directories into
+# the corresponding refpages module directories.
+# The pageMap and xrefMap created by setup_spec_antora are used here.
+
+ANTORA_REFMODULE = antora/refpages/modules/refpages
+# Where to create the extracted refpage files
+ANTORA_EXTRACT_PAGES = $(ANTORA_REFMODULE)/pages/source
+ANTORA_LOGPATH = antora/refpages/
+# Same as SPECFILES but pointing to rewritten partials
+ANTORA_SPECFILES = $(wildcard $(ANTORA_SPECMODULE)/partials/chapters/[A-Za-z]*.adoc $(ANTORA_SPECMODULE)/partials/chapters/*/[A-Za-z]*.adoc $(ANTORA_SPECMODULE)/partials/appendices/[A-Za-z]*.adoc)
+
+setup_refpages_antora: setup_spec_antora xrefMap pageMap $(GENREF) $(SCRIPTS)/reflib.py $(PYAPIMAP)
+	$(QUIET)$(MKDIR) $(ANTORA_EXTRACT_PAGES)
+	$(PYTHON) $(GENREF) -basedir $(ANTORA_EXTRACT_PAGES) \
+	    -diag $(ANTORA_LOGPATH)/refpage.diag \
+	    -warn $(ANTORA_LOGPATH)/refpage.warn \
+	    -extpath $(ANTORA_SPECMODULE)/partials/appendices \
+	    -antora \
+	    -xrefMap $(PYXREFMAP) \
+	    -pageMap $(PYPAGEMAP) \
+	    -module 'spec::' \
+	    -nav $(ANTORA_REFMODULE)/nav.adoc \
+	    $(EXTOPTIONS) $(ANTORA_SPECFILES)
+	$(QUIET)$(RM) $(ANTORA_REFMODULE)/partials && ln -s $(shell realpath $(ANTORA_SPECMODULE)/partials) $(ANTORA_REFMODULE)/partials
+	$(QUIET)$(RM) $(ANTORA_REFMODULE)/images && ln -s $(shell realpath $(ANTORA_SPECMODULE)/images) $(ANTORA_REFMODULE)/images
+
 # This generates a single file containing asciidoc attributes for each
 # core version and extension in the spec being built.
 # For use with Antora, it also includes a couple of document attributes
@@ -903,11 +913,10 @@ clean: clean_html clean_pdf clean_man clean_generated clean_antora clean_validus
 
 clean_html:
 	$(QUIET)$(RMRF) $(HTMLDIR) $(OUTDIR)/katex
-	$(QUIET)$(RM) $(OUTDIR)/apispec.html $(OUTDIR)/styleguide.html \
-	    $(OUTDIR)/registry.html
+	$(QUIET)$(RM) $(OUTDIR)/styleguide.html $(OUTDIR)/registry.html
 
 clean_pdf:
-	$(QUIET)$(RMRF) $(PDFDIR) $(OUTDIR)/apispec.pdf
+	$(QUIET)$(RMRF) $(PDFDIR)
 
 clean_man:
 	$(QUIET)$(RMRF) $(MANHTMLDIR)
@@ -936,7 +945,10 @@ clean_generated:
 	$(QUIET)$(RMRF) $(CLEAN_GEN_PATHS)
 
 # Files generated by 'setup_antora' target
-# Omit antora/features/modules/features/nav.adoc which is generated, but
+# Omit
+#   antora/<module>/modules/<module>/nav.adoc
+# and
+#   antora/<module>/modules/<module>/pages/index.adoc
 # also checked in.
 CLEAN_ANTORA_PATHS = \
 	$(ANTORA_FILELIST) \
@@ -949,6 +961,10 @@ CLEAN_ANTORA_PATHS = \
 	antora/features/modules/features/pages/proposals \
 	antora/features/modules/features/partials \
 	antora/features/modules/features/images \
+	antora/refpages/modules/refpages/pages/source \
+	antora/refpages/modules/refpages/partials \
+	antora/refpages/modules/refpages/images \
+	antora/refpages/refpage.log \
 	$(JSXREFMAP) \
 	$(PYXREFMAP) \
 	$(JSPAGEMAP) \
@@ -959,5 +975,3 @@ clean_antora:
 
 clean_validusage:
 	$(QUIET)$(RM) $(VUDIR)/validusage.json
-
-

antora/features/modules/features/nav.adoc

@@ -9,11 +9,14 @@
 * xref:index.adoc[Vulkan Roadmap and Feature Descriptions]
 * xref:proposals/Roadmap.adoc[Vulkan Roadmap]
 * Feature Descriptions
+** xref:proposals/VK_AMDX_dense_geometry_format.adoc[]
 ** xref:proposals/VK_AMDX_shader_enqueue.adoc[]
 ** xref:proposals/VK_AMD_anti_lag.adoc[]
 ** xref:proposals/VK_AMD_shader_early_and_late_fragment_tests.adoc[]
 ** xref:proposals/VK_ANDROID_external_format_resolve.adoc[]
+** xref:proposals/VK_ARM_pipeline_opacity_micromap.adoc[]
 ** xref:proposals/VK_ARM_render_pass_striped.adoc[]
+** xref:proposals/VK_ARM_tensors.adoc[]
 ** xref:proposals/VK_EXT_attachment_feedback_loop_dynamic_state.adoc[]
 ** xref:proposals/VK_EXT_attachment_feedback_loop_layout.adoc[]
 ** xref:proposals/VK_EXT_calibrated_timestamps.adoc[]
@@ -25,6 +28,8 @@
 ** xref:proposals/VK_EXT_dynamic_rendering_unused_attachments.adoc[]
 ** xref:proposals/VK_EXT_extended_dynamic_state3.adoc[]
 ** xref:proposals/VK_EXT_external_memory_acquire_unmodified.adoc[]
+** xref:proposals/VK_EXT_external_memory_metal.adoc[]
+** xref:proposals/VK_EXT_fragment_density_map_offset.adoc[]
 ** xref:proposals/VK_EXT_frame_boundary.adoc[]
 ** xref:proposals/VK_EXT_graphics_pipeline_library.adoc[]
 ** xref:proposals/VK_EXT_host_image_copy.adoc[]
@@ -46,13 +51,15 @@
 ** xref:proposals/VK_EXT_present_mode_fifo_latest_ready.adoc[]
 ** xref:proposals/VK_EXT_primitives_generated_query.adoc[]
 ** xref:proposals/VK_EXT_rasterization_order_attachment_access.adoc[]
+** xref:proposals/VK_EXT_shader_float8.adoc[]
 ** xref:proposals/VK_EXT_shader_module_identifier.adoc[]
 ** xref:proposals/VK_EXT_shader_object.adoc[]
 ** xref:proposals/VK_EXT_shader_replicated_composites.adoc[]
 ** xref:proposals/VK_EXT_shader_tile_image.adoc[]
 ** xref:proposals/VK_EXT_subpass_merge_feedback.adoc[]
 ** xref:proposals/VK_EXT_surface_maintenance1.adoc[]
 ** xref:proposals/VK_EXT_swapchain_maintenance1.adoc[]
+** xref:proposals/VK_EXT_zero_initialize_device_memory.adoc[]
 ** xref:proposals/VK_GOOGLE_surfaceless_query.adoc[]
 ** xref:proposals/VK_HUAWEI_cluster_culling_shader.adoc[]
 ** xref:proposals/VK_HUAWEI_invocation_mask.adoc[]
@@ -66,33 +73,53 @@
 ** xref:proposals/VK_KHR_maintenance5.adoc[]
 ** xref:proposals/VK_KHR_maintenance6.adoc[]
 ** xref:proposals/VK_KHR_maintenance7.adoc[]
+** xref:proposals/VK_KHR_maintenance8.adoc[]
+** xref:proposals/VK_KHR_maintenance9.adoc[]
 ** xref:proposals/VK_KHR_map_memory2.adoc[]
 ** xref:proposals/VK_KHR_pipeline_binary.adoc[]
+** xref:proposals/VK_KHR_present_id2.adoc[]
+** xref:proposals/VK_KHR_present_mode_fifo_latest_ready.adoc[]
+** xref:proposals/VK_KHR_present_wait2.adoc[]
 ** xref:proposals/VK_KHR_ray_tracing_position_fetch.adoc[]
+** xref:proposals/VK_KHR_shader_bfloat16.adoc[]
 ** xref:proposals/VK_KHR_shader_expect_assume.adoc[]
 ** xref:proposals/VK_KHR_shader_float_controls2.adoc[]
 ** xref:proposals/VK_KHR_shader_integer_dot_product.adoc[]
 ** xref:proposals/VK_KHR_shader_maximal_reconvergence.adoc[]
 ** xref:proposals/VK_KHR_shader_quad_control.adoc[]
 ** xref:proposals/VK_KHR_shader_relaxed_extended_instruction.adoc[]
 ** xref:proposals/VK_KHR_shader_subgroup_rotate.adoc[]
+** xref:proposals/VK_KHR_shader_untyped_pointers.adoc[]
+** xref:proposals/VK_KHR_surface_maintenance1.adoc[]
+** xref:proposals/VK_KHR_swapchain_maintenance1.adoc[]
+** xref:proposals/VK_KHR_unified_image_layouts.adoc[]
 ** xref:proposals/VK_KHR_vertex_attribute_divisor.adoc[]
 ** xref:proposals/VK_KHR_video_decode_av1.adoc[]
 ** xref:proposals/VK_KHR_video_decode_h264.adoc[]
 ** xref:proposals/VK_KHR_video_decode_h265.adoc[]
 ** xref:proposals/VK_KHR_video_decode_queue.adoc[]
+** xref:proposals/VK_KHR_video_decode_vp9.adoc[]
 ** xref:proposals/VK_KHR_video_encode_av1.adoc[]
 ** xref:proposals/VK_KHR_video_encode_h264.adoc[]
 ** xref:proposals/VK_KHR_video_encode_h265.adoc[]
+** xref:proposals/VK_KHR_video_encode_intra_refresh.adoc[]
 ** xref:proposals/VK_KHR_video_encode_quantization_map.adoc[]
 ** xref:proposals/VK_KHR_video_encode_queue.adoc[]
 ** xref:proposals/VK_KHR_video_maintenance1.adoc[]
+** xref:proposals/VK_KHR_video_maintenance2.adoc[]
 ** xref:proposals/VK_KHR_video_queue.adoc[]
 ** xref:proposals/VK_LUNARG_direct_driver_loading.adoc[]
 ** xref:proposals/VK_MSFT_layered_driver.adoc[]
+** xref:proposals/VK_NV_cluster_acceleration_structure.adoc[]
 ** xref:proposals/VK_NV_cooperative_matrix2.adoc[]
+** xref:proposals/VK_NV_cooperative_vector.adoc[]
 ** xref:proposals/VK_NV_display_stereo.adoc[]
+** xref:proposals/VK_NV_external_compute_queue.adoc[]
+** xref:proposals/VK_NV_partitioned_acceleration_structure.adoc[]
+** xref:proposals/VK_NV_ray_tracing_linear_swept_spheres.adoc[]
 ** xref:proposals/VK_NV_ray_tracing_validation.adoc[]
 ** xref:proposals/VK_QCOM_image_processing.adoc[]
+** xref:proposals/VK_QCOM_tile_memory_heap.adoc[]
 ** xref:proposals/VK_QCOM_tile_properties.adoc[]
+** xref:proposals/VK_QCOM_tile_shading.adoc[]
 ** xref:proposals/VK_VERSION_1_4.adoc[]

antora/refpages/antora.yml

@@ -0,0 +1,28 @@
+# Copyright 2022-2025 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+name: refpages
+title: Vulkan API Reference Pages
+version: latest
+start_page: refpages:index.adoc
+# stem (latexmath) support is provided by the @djencks/asciidoctor-mathjax
+# extension, loaded in the playbook.
+asciidoc:
+  attributes:
+    stem: latexmath
+    config: partial$config
+    chapters: partial$chapters
+    appendices: partial$appendices
+    generated: partial$gen
+    images: image$
+# Not supported for SVG yet - see https://gitlab.com/antora/antora/-/issues/1001
+#    imageopts: inline
+    imageopts: ''
+    refprefix: ''
+# This causes custom link macros (flink:, slink:, etc.) to link to another
+# refpage, instead of to the specification itself.
+    cross-file-links: true
+# This includes some content not in the spec itself
+    isrefpage: true
+nav:
+- modules/refpages/nav.adoc