Cross-references
Cross-references (xref) are a special syntax used to create links between documents within your documentation site. Using xref links allows you to reference other documents without using relative file paths. This makes it easier to reorganize your documentation structure without breaking links, as Tanka Docs will validate these references during generation.
There are three ways to use xref links:
1. Reference a document in the current section
This is the simplest form of xref. It's used when you want to link to another document that resides within the same documentation section.
Syntax:
[Link Text](xref://document-name.md)
Example:
If you are in section-a/page-one.md and want to link to section-a/page-two.md, you would use:
[Go to Page Two](xref://page-two.md)
2. Reference a document in a different section
When you need to link to a document in a different section, you must prefix the document name with the ID of the target section.
Syntax:
[Link Text](xref://sectionId:document-name.md)
Example:
If you are in section-a/page-one.md and want to link to section-b/introduction.md (assuming section-b has an ID of b-docs), you would use:
[Read Section B Intro](xref://b-docs:introduction.md)
3. Reference a document in a different section and version
For projects with multiple versions, you can link to a document in a specific version of a section. This is done by adding the version number after the section ID, separated by an @ symbol.
Syntax:
[Link Text](xref://sectionId@version:document-name.md)
Example:
If you are in section-a/page-one.md (version 2.0.0) and want to link to section-b/release-notes.md from version 1.0.0 (assuming section-b has an ID of b-docs), you would use:
[View v1.0.0 Release Notes](xref://b-docs@1.0.0:release-notes.md)
Cross-reference Images
Cross-references also work with images! You can reference images stored in other sections using the same xref:// syntax. This is particularly useful for sharing logos, diagrams, or other assets across multiple sections.
Syntax:
Examples:
<!-- Reference image in current section -->
<!-- Reference image from a different section -->
<!-- Reference image from specific version -->
Asset Processing
When you reference an image using xref:// syntax:
- Resolution: The xref URL is resolved to the actual file path during build
- Copying: The referenced image is automatically copied to the output directory
- Path Generation: The image URL follows the same pattern as HTML pages for consistency
- Cross-Section Support: Images from other sections are tracked and copied correctly
Supported Image Formats:
.png,.jpg,.jpeg,.gif,.svg,.webp,.bmp,.ico,.tiff
Important Restrictions
HEAD Version Restriction
The HEAD version in xref links is restricted to ensure documentation builds are reproducible and stable. HEAD is only allowed when it's explicitly configured as a version in your tanka-docs.yml file (typically only used for development builds).
Production builds (HEAD not configured):
# These will cause build errors in production
[Link](xref://section@HEAD:file.md) ❌
 ❌
# Use these instead
[Link](xref://section@master:file.md) ✅
[Link](xref://section@1.0.0:file.md) ✅
[Link](xref://section:file.md) ✅ (uses current context)
Development builds (with HEAD configured in tanka-docs-wip.yml):
branches:
HEAD:
input_path:
- docs
When HEAD is configured as above, xref://section@HEAD:file.md references will work normally.
Error message when HEAD is not configured:
Invalid xref reference: xref://section@HEAD:file.md - HEAD version is not allowed.
Use a specific version or omit the version to use the current context.
This comprehensive format ensures that all variations are documented with clear explanations and examples.