Document the guides API, and move Guides beside Slides
The repo already enforces that every served route appears in docs/api-inventory.json, and the guides endpoints did not - so the parity test was failing. They are now listed with auth, params and a working example each, beside knowledgebase because the two get read for the same reason. docs/GUIDES.md covers what the inventory cannot: the block schema and why it is blocks rather than HTML, the id rule that makes a tick rememberable, what the server refuses and why validation happens at the door, the working-copy / revision / published-pointer split that stops a live procedure changing under somebody following it, and a worked example of creating and publishing a guide from a script. It also states plainly what does not exist yet - no importer, orphaned images never pruned - and what converting existing documents will actually be like: structured HTML and Markdown map onto block types nearly one for one, while a plain-text runbook lands as paragraphs and needs marking up by hand afterwards. Generated ids have to stay stable across re-imports, or every re-import resets readers' progress. Guides moves to position 8 in the sidebar, beside Slides, rather than down among the reference lists in Information. A guide is something somebody goes and does something with, not a catalogue they look things up in.
This commit is contained in:
@@ -75,13 +75,16 @@ class GuidesPlugin(BasePlugin):
|
||||
]
|
||||
|
||||
def get_navigation_items(self) -> List[Dict]:
|
||||
# Position 8, beside Slides (7), rather than down in the Information
|
||||
# section with the reference lists. A guide is something you go and DO
|
||||
# something with, like a slide deck you put on a screen - not a
|
||||
# catalogue you look things up in.
|
||||
return [
|
||||
{
|
||||
'name': 'Guides',
|
||||
'icon': 'book-open',
|
||||
'route': '/guides',
|
||||
'position': 36,
|
||||
'section': 'information',
|
||||
'position': 8,
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user