Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
75390f9
Refine structured v3 YAML authoring
addshore Nov 11, 2026
c3dfa40
Remove redundant v3 exchange metadata
addshore Nov 11, 2026
d6ecafe
Remove omitted presence from v3 docs
addshore Nov 11, 2026
3d1496f
Remove Authoring exchange field section
addshore Nov 11, 2026
7aae7fc
Re add something I didnt want to remove
addshore Nov 11, 2026
4746937
Correct GPS and MT34 response documentation
addshore Nov 11, 2026
f516d10
Correct v3 message sidebar grouping
addshore Nov 11, 2026
f1bed73
Remove redundant fixed-width limits
addshore Nov 11, 2026
7736b19
Consolidate GPS Control field guidance
addshore Nov 11, 2026
8140ec8
Model V3 exchanges as additive versioned interactions
addshore Nov 11, 2026
7ff499b
Define V3 usage interactions inline with each message
addshore Nov 11, 2026
d79e280
Simplify documented request inputs and retain exception guidance
addshore Nov 11, 2026
7968752
Clarify GSM summary and link message references
addshore Nov 11, 2026
c72c191
Centralize response correlation guidance
addshore Nov 11, 2026
ab6fea6
Link message references throughout protocol prose
addshore Nov 11, 2026
1539bd1
Finish interaction authoring guidance and preserve SDK compatibility
addshore Nov 11, 2026
5745361
Flatten interactions and keep documentation metadata out of the protocol
addshore Nov 11, 2026
1e1d476
Inherit shared V3 field and error descriptions
addshore Nov 11, 2026
b292df7
Reuse scoped YAML fragments and export expanded protocol
addshore Nov 11, 2026
3b8b212
Trim brittle documentation tests and assert specific diagnostics
addshore Nov 11, 2026
9ec28aa
Preserve resolved response header constraints in tests
addshore Nov 11, 2026
9ec31ee
Refactor responses documentation for clarity and accuracy
addshore Nov 12, 2026
d379e75
Delete YAML specification from protocol index
addshore Nov 12, 2026
dbe5b15
test: remove assertions for removed protocol prose and examples
addshore Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import path from 'path';
import fs from 'fs';
import yaml from 'js-yaml';
import { createRequire } from 'node:module';
import { defineConfig } from 'vitepress';
import { useSidebar } from 'vitepress-openapi';
import { loadSpec } from '../swagger/load';
Expand All @@ -20,6 +21,10 @@ import { capabilitySidebar } from '../utils/DeviceCapabilities';


const base = process.env.PREVIEW_BASE || "/"
// Keep the shared Node CLI helpers outside Vite's ESM config bundle.
const requireFromConfig = createRequire(import.meta.url);
const expandedProtocolPlugin = requireFromConfig(path.resolve(__dirname, './plugins/expanded-protocol.cjs'));
const expandedProtocol = requireFromConfig(path.resolve(__dirname, '../utils/expanded-protocol.cjs'));

// Load protocol messages from YAML file
const protocolYamlPath = path.resolve(__dirname, '../public/files/protocol-v3.yaml');
Expand Down Expand Up @@ -203,6 +208,9 @@ export default withMermaid(defineConfig({
description: "home for everything Lightbug",
lang: 'en-GB',
cleanUrls: true,
buildEnd(siteConfig) {
expandedProtocol.writeExpandedProtocol(siteConfig.outDir, protocolYamlPath);
},
sitemap: {
hostname: process.env.DEPLOYMENT_NAME === 'Production' ? 'https://docs.lightbug.io' : 'https://docs-next.lightbug.io'
},
Expand All @@ -223,6 +231,7 @@ export default withMermaid(defineConfig({
noExternal: ["vuetify", "vitepress-openapi"]
},
plugins: [
expandedProtocolPlugin(protocolYamlPath, base),
// Keep the native samples export available on versions that omit it.
{
name: 'prototype-native-code-samples-export',
Expand Down
23 changes: 23 additions & 0 deletions .vitepress/plugins/expanded-protocol.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
const { readExpandedProtocol, expandedProtocolFilename } = require('../../utils/expanded-protocol.cjs');

// Production uses VitePress's buildEnd hook. Serve the same export directly
// from the canonical source in development, without an intermediate file.
module.exports = function expandedProtocolPlugin(sourcePath, base = '/') {
const downloadPath = `${base.replace(/\/$/, '')}/files/${expandedProtocolFilename}`;
return {
name: 'expanded-protocol-download',
configureServer(server) {
server.middlewares.use((request, response, next) => {
if (!['GET', 'HEAD'].includes(request.method) || request.url?.split('?')[0] !== downloadPath) return next();
try {
const source = readExpandedProtocol(sourcePath);
response.setHeader('Content-Type', 'application/yaml; charset=utf-8');
response.setHeader('Cache-Control', 'no-cache');
response.end(request.method === 'HEAD' ? undefined : source);
} catch (error) {
next(error);
}
});
},
};
};
55 changes: 55 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,61 @@ Both scripts use `cross-env` so they work cross-platform.

PR preview workflows and administrator setup: [.github/preview](https://github.com/lightbug-io/docs/blob/main/.github/preview/README.md).

## Protocol YAML authoring and export

`public/files/protocol-v3.yaml` is the canonical source. It uses native YAML
anchors (`&name`), aliases (`*name`) and merge keys (`<<: *name`), parsed by the
same `js-yaml` dependency used by the docs. There is no separate template engine.
Consumers without merge-key support can use the expanded export below.

- Definitions used only within one message are anchored at their first use in
that message. Use message-specific anchor names: anchors have document scope,
not message scope, and must appear before their aliases.
- Only header maps shared across messages live in the top-level
`templates.headers` registry: `optionalOkReply`, `correlatedOkAck`, and
`optionalCorrelationAck`. An anchor has no effect unless explicitly aliased
or merged into an actual message definition.
- A YAML merge is shallow. An explicit key replaces that entire merged value;
replacing a header entry does not inherit the entry's other properties.
Anchor smaller maps when individual nested values need to be reused.

### Navigate shared definitions

In VS Code with [Red Hat YAML](https://github.com/redhat-developer/vscode-yaml),
put the caret on an alias (`*name`) and run **Go to Definition** from the context
menu. The extension's language server
[resolves aliases to their anchors](https://github.com/redhat-developer/yaml-language-server/blob/main/src/languageservice/services/yamlDefinition.ts).
This follows the explicit alias, not an inherited field name or arbitrary string.

[IntelliJ IDEA's YAML support](https://www.jetbrains.com/help/idea/yaml.html)
documents alias-to-anchor navigation, anchor usages, and anchor/alias rename.
Use **Go to Declaration or Usages**; the shortcut depends on your key bindings.
These are editor features, not something the docs site adds. If your editor or
extension version lacks them, search for `&name` in the canonical file. The
expanded download below is useful for inspecting all values without jumping.

### Export expanded YAML

The protocol overview offers **Download expanded YAML** at
`files/protocol-v3-expanded.yaml`, including on PR previews. The build creates it
from the canonical source; the development server generates it on each request.
Do not commit or edit a second generated specification.

To inspect or save the same output locally after installing dependencies:

```bash
npm run --silent export:protocol
npm run --silent export:protocol > /tmp/protocol-v3-expanded.yaml
```

The export resolves aliases and merge keys using the `yaml` library's typed
maps, keeping numeric keys as integers and deliberately quoted keys as strings
for SDK generator compatibility. It emits no anchors and removes only
the top-level authoring-only `templates` registry. All other parsed data is
preserved, including sentinels and version overrides. It does not invent runtime
defaults or flatten message-version description inheritance. Comments and
source formatting are not retained. Edit the canonical source and re-export.

## Protocol sentinel values

Numeric field definitions in `public/files/protocol-v3.yaml` can declare raw
Expand Down
7 changes: 4 additions & 3 deletions components/Protocol/DocumentationText.vue
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
<script setup lang="ts">
import { computed } from 'vue'
import { withBase } from 'vitepress'
import { documentationTextParts } from '../../utils/MessageDocumentation'
const props = defineProps<{ text: string }>()
const parts = computed(() => documentationTextParts(props.text))
const props = defineProps<{ text: string; messages?: Record<string, any> }>()
const parts = computed(() => documentationTextParts(props.text, props.messages, withBase))
</script>

<template>
<template v-for="(part, index) in parts" :key="index">
<a v-if="part.href" :href="part.href" target="_blank" rel="noopener noreferrer">{{ part.text }}</a><template v-else>{{ part.text }}</template>
<a v-if="part.href" :href="part.href" :target="part.href.startsWith('http') ? '_blank' : undefined" :rel="part.href.startsWith('http') ? 'noopener noreferrer' : undefined">{{ part.text }}</a><template v-else>{{ part.text }}</template>
</template>
</template>
Loading
Loading