# Vulkan-Guide: Khronos maps the routes through Vulkan so you do not have to > A documentation project rather than a library, written in AsciiDoc and published to docs.vulkan.org, whose value is in indexing the API by the problem you are actually trying to solve. **KhronosGroup/Vulkan-Guide** — One stop shop for getting started with the Vulkan API - Repository: https://github.com/KhronosGroup/Vulkan-Guide - Stars: 2,286 · Forks: 196 - Language: Makefile - License: CC-BY-4.0 - Published: 2026-10-07 · Updated: 2026-10-07 · Language: en - Canonical page: https://hysenlabs.com/projects/khronosgroup-vulkan-guide ## A document, not a library, with an unusual language label GitHub reports the primary language of this repository as Makefile. That is not a mistake in the metadata; there is no library here to compile. The deliverable is the text, and the build tooling is what is written in a language the detector recognises. The project describes itself as a one stop shop for getting started with the Vulkan API, and it is worth taking that phrase literally rather than as marketing. The stated aim is to be a light read that leads to many other useful links depending on what a developer is looking for, with the goal of filling gaps about the many nuances of Vulkan. That is a different contract from a tutorial, and it changes what you should expect when you open it. Concretely, you are not going to find a complete worked example here. You are going to find a curated table of contents where every line is a pointer to a specific confusion, and the documentation site carries the actual prose. Licensing is CC-BY-4.0, which is the right choice for a document of this kind and is a visible signal that the maintainers intend it to be reused and translated. It has 2,286 stars, 196 forks, and a last push on 2026-09-27. ## How the source becomes a website The repository root is a small set of files that mostly matter for the build. There is `README.adoc` as the master document, a `README.md` rendered for people who land on GitHub, an `antora/` directory holding the site configuration, `REUSE.toml` for licence metadata, and a `LICENSE` plus `LICENSES/` directory following the REUSE convention that Khronos applies across its documentation projects. Antora is the documentation site generator, and the `:data-uri:` and `:source-highlighter: rouge` attributes in the master document show how it is configured. The README carries a note that the same content is viewable at docs.vulkan.org/guide/latest/index.html, which is the URL to cite if you link to this work. Two details are quietly good practice. The document declares `:numbered:` and `:toc:`, so cross references resolve to numbered sections rather than to a flat list. And it sets `:chapters: chapters/` with an explanatory comment above it, because the implicit `{relfileprefix}` does not work given the file hierarchy. That is the kind of note that only gets written after losing an afternoon to it. The `lang/` directory holds `jp/` and `kor/`, and the master document links both as sibling README files. So Japanese and Korean translations exist as parallel documents rather than as generated locales, which means translators edit prose rather than strings. ## Organized by the question, not by spec order The table of contents is the argument for the project, so it is worth reading rather than skimming. The chapters are grouped into three top-level sections: a logistics overview, using Vulkan, and when and why to use extensions. The logistics group is where a newcomer starts and where most of the value sits: What is Vulkan, what you can do with Vulkan, the spec, platforms, checking for support, versions and a porting guide, the release summary, what SPIR-V is, the portability initiative, the Vulkan CTS, development tools, a validation overview, profiling, and a chapter called the Vulkan Decoder Ring that maps GL, GLES, DirectX and Metal onto Vulkan equivalents. That last one is the kind of chapter that saves the most time. Vulkan's abstraction is explicit and layered where other APIs hide it, so developers arriving from Direct3D or Metal routinely get stuck on Vulkan-specific vocabulary with no mental model. A document that translates between those vocabularies is more useful than one that teaches Vulkan from first principles, because the concepts are mostly already known. The SPIR-V chapter and the portability initiative sit next to each other for good reason. Both answer the question a cross-platform team actually asks, which is how much of this code can run on the other platforms. ## The hard middle of the API, chapter by chapter Once past the orientation material, the Using Vulkan section becomes a catalogue of the parts that make Vulkan Vulkan. Synchronization gets three chapters of its own plus one on porting to VK_KHR_synchronization2 and one on swapchain semaphore reuse. Memory allocation strategy gets its own chapter, with nested pages for sparse resources, protected memory and buffer device address, the last two naming the extensions they correspond to. The pattern repeats, and it is the pattern that makes the guide useful. Every nested entry lists the extension names it relates to, in backticks, directly under the topic. Queue family, WSI, pNext and sType, threading, depth, primitive topology, pipeline caching, compute shaders, subgroups, atomics, shader memory layout: each is a page that exists because these are the places people get stuck. Two chapters stand out for practical reasons. Common Pitfalls is the one to read before you start, because reading it after debugging a synchronization bug for two days is a different experience. And High Level Shader Language Comparison sits next to HLSL and Slang usage chapters, which is the question that dominates the first week for most teams arriving from D3D. Buffer device address gets two pages rather than one, and descriptor handling gets four: descriptor arrays, dynamic offsets, VK_EXT_descriptor_buffer and VK_EXT_descriptor_heap. The level of granularity here is the point. Nobody writes a page for something nobody has asked about. ## A reference index rather than an advocacy document One callout sets the tone for the extension section: these are supplemental references for the various Vulkan extensions, and you should consult the Vulkan Spec for further details on any of them. The Guide positions itself underneath the spec rather than beside it. There is a NOTE block in the opening that makes the same point about content being viewable on the documentation site, and the site carries the Antora build of the same source. So there is one body of text with two rendering paths, and the version pinned to `latest` on the site is the moving one. What the project does not do is benchmark, recommend hardware, or argue that Vulkan is the right choice for your project. The chapter on what Vulkan can do is a capability description, not a sales pitch. If you are deciding whether to adopt Vulkan at all, this repository will tell you what the API can express and will be silent on whether your team should take it on. The build system is Makefile-based, which fits a documentation project where the interesting tooling is AsciiDoc, Antora and Rouge rather than a compiler. For contributors, `CONTRIBUTING.adoc` is the entry point, and `CODE_OF_CONDUCT.adoc` sits beside it, both in the AsciiDoc form used across Khronos repositories. ## Conclusion Vulkan-Guide is best understood as a routing table, not a tutorial. It will not walk you through writing a triangle; the Getting Started tutorial and the samples repository do that. What it does is hold the map that the spec cannot: which extension to reach for, which chapter explains why a thing is shaped strangely, and which validation layer will catch the mistake you are about to make. Published as docs.vulkan.org/guide, updated on 2026-09-27, with only seven open issues against 2,286 stars. ## FAQ ### How do I know if my GPU is Vulkan capable? The Guide has a chapter on checking for support, listed alongside platforms and the spec under its logistics overview. That chapter is where the runtime enumeration approach belongs, rather than trying to identify a driver from a specification sheet. ### Is Vulkan difficult to learn? The Guide does not argue that it is easy. It describes itself as a light read designed to lead to other useful links, and its structure, with dedicated chapters on synchronization, memory allocation strategy and common pitfalls, is an acknowledgement that the API has a lot of concepts to hold at once. That is the gap it exists to fill. ### What is the difference between the Vulkan Guide and the Vulkan spec? The spec is normative and defines the API. The Guide is a curated, non-normative index that maps problems to chapters and names the relevant extensions beside each topic. Its own callout says to consult the spec for details on any extension. ### Where should I start learning Vulkan from scratch? The Guide is a routing table, not a tutorial, and it says so. For a first program, the Khronos Getting Started in Vulkan tutorial is the companion resource it links alongside the samples repository. For orientation on what the API can express, start with the Guide's what-is-Vulkan and what-you-can-do chapters. ### Is Vulkan-Guide available in other languages? Japanese and Korean versions exist. The repository keeps them under a lang directory as parallel AsciiDoc documents, with README-jp.adoc and README-kor.adoc linked from the master document, so translators work on prose rather than generated locale strings. ## Sources - [Issues](https://github.com/KhronosGroup/Vulkan-Guide/issues) - [KhronosGroup/Vulkan-Guide on GitHub](https://github.com/KhronosGroup/Vulkan-Guide) - [License: CC-BY-4.0](https://github.com/KhronosGroup/Vulkan-Guide/blob/main/LICENSE) - [README](https://github.com/KhronosGroup/Vulkan-Guide/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/khronosgroup-vulkan-guide