NIP-XX
======
Documentation Spaces
draft optional
This NIP defines a comprehensive documentation and wiki system using multiple event kinds to organize content into spaces and pages with support for various markup formats.
## Overview
This NIP introduces a hierarchical documentation system where:
- Documentation Spaces (kind:33527) define containers for related documentation
- Documentation Pages (kind:39561) contain the actual content within spaces
- Pages support multiple markup formats: HTML, Wikitext, Markdown, and AsciiDoc
- Spaces can be public or private, with configurable access controls
## Event Kinds
### Documentation Space (kind:33527)
Defines a documentation space - a container for related pages.
```json
{
"kind": 33527,
"content": "# Welcome to My Project\n\nThis is the start page for our documentation space. You can use any supported markup format here.\n\nSee [[Getting Started]] to begin, or browse our [[API Reference]].",
"tags": [
["d", "my-project-docs"],
["title", "My Project Documentation"],
["description", "Complete documentation for My Project"],
["format", "markdown"],
["default_format", "markdown"],
["visibility", "public"],
["homepage", "introduction"]
]
}
```
Required tags:
- d: Unique identifier for the space (normalized according to rules below)
- title: Human-readable name of the documentation space
Optional tags:
- description: Brief description of the space's purpose
- format: Markup format for the content field (html, wikitext, markdown, asciidoc)
- default_format: Default markup format for new pages (html, wikitext, markdown, asciidoc)
- visibility: Access level (public, private, unlisted)
- homepage: d tag identifier of the default page to display (if not using content as start page)
- t: Category tags for discovery (e.g., documentation, wiki, api-docs)
Content field:
The content field can optionally contain a start page for the documentation space. If present, this content will be displayed as the default landing page when users visit the space. If empty, clients should display the page specified by the homepage tag, or provide a directory listing of available pages.
### Documentation Page (kind:39561)
Contains the actual documentation content within a space.
```json
{
"kind": 39561,
"content": "# Welcome\n\nThis is the introduction page written in Markdown.",
"tags": [
["d", "introduction"],
["space", "my-project-docs"],
["title", "Introduction"],
["format", "markdown"],
["parent", "getting-started"]
]
}
```
Required tags:
- d: Unique identifier for the page within its space
- space: The d tag identifier of the parent documentation space
- title: Human-readable page title
- format: Markup format used (html, wikitext, markdown, asciidoc)
Optional tags:
- parent: d tag identifier of parent page (for hierarchical organization)
- summary: Brief description for page listings
- order: Numeric value for custom ordering within parent (lower numbers first)
- t: Category tags for the page content
## Identifier Normalization Rules
Both space and page identifiers in d tags must follow these normalization rules:
- Convert to lowercase
- Replace any non-alphanumeric character with -
- Remove leading/trailing -
- Collapse multiple consecutive - into single -
- Maximum length of 64 characters
Examples:
- "My Project Docs" → my-project-docs
- "API Reference v2.0" → api-reference-v2-0
- "Getting Started!!!" → getting-started
## Supported Markup Formats
### HTML (format: "html")
Standard HTML content. Should be sanitized by clients for security.
### Wikitext (format: "wikitext")
MediaWiki-style markup with support for:
- [[Page Name]] - Links to other pages in the same space
- [[Space:Page Name]] - Links to pages in other spaces
- [[Page Name|Display Text]] - Links with custom display text
### Markdown (format: "markdown")
CommonMark-compatible Markdown with extensions:
- [Page Name]() - Links to other pages (resolved by client)
- [Display Text](page-id) - Links with explicit page identifier
- Standard Markdown syntax for formatting
### AsciiDoc (format: "asciidoc")
AsciiDoc markup with cross-reference support:
- <<page-id>> - Links to other pages in the same space
- <<space:page-id>> - Links to pages in other spaces
- <<page-id,Display Text>> - Links with custom display text
## Cross-References and Linking
### Wikilinks (Universal)
All markup formats support wikilinks using double square brackets [[]], inspired by NIP-54. This provides a consistent linking syntax across all formats:
#### Basic Wikilinks
- [[target-page]] - Links to target-page in the same space, displayed as "Target Page"
- [[target-page|Custom Display]] - Links to target-page but displays as "Custom Display"
#### Cross-Space Wikilinks
- [[other-space:target-page]] - Links to target-page in other-space
- [[other-space:target-page|See Documentation]] - Cross-space link with custom display text
#### Wikilink Resolution Rules
1. Page identifier normalization: [[My Cool Page]] resolves to page with d tag my-cool-page
2. Display text generation: If no custom display text is provided, convert the identifier back to title case
3. Space resolution: If no space is specified, assume current space
4. Broken link handling: Clients should clearly indicate when wikilinks point to non-existent pages
### Format-Specific Links
In addition to universal wikilinks, each format retains its native linking syntax:
#### Markdown
- [Display Text](target-page) - Standard markdown link to page in same space
- [Display Text](other-space:target-page) - Cross-space markdown link
- [Display Text](https://example.com) - External URL
#### Wikitext
- Native wikilink syntax is the same as universal wikilinks
- [https://example.com Display Text] - External links
#### AsciiDoc
- <<target-page>> or <<target-page,Display Text>> - Cross-references
- Display Text - External links
#### HTML
- <a href="target-page">Display Text</a> - Internal links
- <a href="https://example.com">Display Text</a> - External links
### External Links
Standard web URLs work in all formats according to their respective specifications.
### Nostr Links
All formats support nostr:... links as per NIP-21 for referencing Nostr events and profiles:
- nostr:npub1... - Profile links
- nostr:note1... - Event links
- nostr:naddr1... - Addressable event links
### Link Processing Priority
When processing content, clients should handle links in this order:
1. Wikilinks [[...]] - Highest priority, processed first
2. Nostr links nostr:... - Second priority
3. Format-specific links - Processed according to markup format rules
4. Plain URLs - Auto-linked if format supports it
## Querying Documentation
### Find All Spaces
```json
{
"kinds": [33527],
"#t": ["documentation"]
}
```
### Find Pages in a Space
```json
{
"kinds": [39561],
"#space": ["my-project-docs"]
}
```
### Find Specific Page
```json
{
"kinds": [39561],
"#space": ["my-project-docs"],
"#d": ["introduction"]
}
```
## Access Control and Permissions
### Public Spaces
Spaces with visibility: "public" are discoverable and readable by anyone.
### Private Spaces
Spaces with visibility: "private" should only be accessible to authorized users. Clients may implement access control through:
- Relay-based permissions
- Encrypted content (using NIP-44)
- Custom authentication mechanisms
### Unlisted Spaces
Spaces with visibility: "unlisted" are not included in public discovery but are readable if the space identifier is known.
## Versioning and History
Since both space and page events are addressable (replaceable), each edit creates a new version. Clients should:
- Store previous versions for history tracking
- Provide diff/comparison capabilities
- Allow reverting to previous versions
## Client Implementation Guidelines
### Rendering
- Clients should render content according to the specified format tag
- Cross-references should be resolved to clickable links
- Broken links should be clearly indicated
### Editing
- Provide format-appropriate editors (WYSIWYG for HTML, syntax highlighting for others)
- Validate markup before publishing
- Show preview capabilities
### Navigation
- Implement breadcrumb navigation for hierarchical pages
- Provide search within spaces
- Support table of contents generation
### Caching
- Cache space and page metadata for performance
- Implement efficient update mechanisms
- Handle offline scenarios gracefully
## Migration from NIP-54
This NIP is designed to replace NIP-54 while maintaining backwards compatibility and addressing the format flexibility issues that made NIP-54's AsciiDoc requirement problematic.
### Key Improvements
1. Format Flexibility: Support for HTML, Wikitext, Markdown, AsciiDoc vs. AsciiDoc-only requirement
2. Backwards Compatibility: Existing Markdown content can be preserved without conversion
3. Structured Organization: Explicit spaces vs. global wiki namespace
4. Hierarchical Pages: Parent-child relationships vs. flat structure
5. Access Control: Built-in visibility controls vs. public-only
6. Universal Wikilinks: Consistent [[]] syntax across all formats
7. Start Pages: Optional content in space events for landing pages
### Addressing NIP-54's Compatibility Issues
The Problem: NIP-54's switch from Markdown to AsciiDoc broke backwards compatibility, rendering hundreds of existing articles unusable and creating a barrier to adoption.
The Solution: This NIP supports multiple markup formats, allowing:
- Existing Markdown content to be preserved as-is
- New AsciiDoc content for users who prefer its advanced features
- Mixed format spaces where different pages use different markup
- Gradual migration without breaking existing content
### Migration Strategies
#### Option 1: Preserve Existing Format
```json
{
"kind": 39561,
"content": "# Original Markdown Content\n\nThis content stays exactly as it was...",
"tags": [
["d", "my-article"],
["space", "migrated-wiki"],
["title", "My Article"],
["format", "markdown"]
]
}
```
#### Option 2: Convert to Preferred Format
```json
{
"kind": 39561,
"content": "= Original Content Converted\n\nThis content has been converted to AsciiDoc...",
"tags": [
["d", "my-article"],
["space", "migrated-wiki"],
["title", "My Article"],
["format", "asciidoc"],
["a", "30818:<original-author>:my-article", "<relay>"],
["e", "<original-event-id>", "<relay>", "fork"]
]
}
```
### Automated Migration Tools
Implementers should provide tools to:
1. Bulk import NIP-54 articles into documentation spaces
2. Format detection and preservation of existing markup
3. Wikilink conversion from NIP-54 syntax to universal syntax
4. Cross-reference mapping between old and new article identifiers
5. History preservation using a and e tags to reference original events
### Coexistence Period
During transition, clients may support both NIP-54 (kind:30818) and this NIP simultaneously, allowing users to migrate at their own pace without losing access to existing content.
## Examples
### Complete Documentation Space
```json
{
"kind": 33527,
"content": "",
"tags": [
["d", "nostr-protocol-docs"],
["title", "Nostr Protocol Documentation"],
["description", "Official documentation for the Nostr protocol"],
["default_format", "markdown"],
["visibility", "public"],
["homepage", "overview"],
["t", "documentation"],
["t", "protocol"],
["t", "nostr"]
]
}
```
### Hierarchical Page Structure
```json
{
"kind": 39561,
"content": "# Getting Started\n\nWelcome to Nostr development...",
"tags": [
["d", "getting-started"],
["space", "nostr-protocol-docs"],
["title", "Getting Started"],
["format", "markdown"],
["order", "1"]
]
}
```
```json
{
"kind": 39561,
"content": "# Installation\n\nTo install a Nostr client...",
"tags": [
["d", "installation"],
["space", "nostr-protocol-docs"],
["title", "Installation"],
["format", "markdown"],
["parent", "getting-started"],
["order", "1"]
]
}
```
### Cross-Reference Examples
Universal Wikilinks (work in all formats):
```markdown
# NIPs Overview
For more details, see [[Event Structure]] and [[Client Implementation]].
Cross-space reference: [[relay-docs:Configuration|Relay Setup Guide]].
You can also check [[protocol-specs:NIP-01|Basic Protocol]] for fundamentals.
```
Markdown with mixed linking:
```markdown
# Getting Started
Start with [[Installation]] (wikilink), then read our
[detailed guide](advanced-setup) (markdown link).
External reference: [NIP-01](nostr:naddr1...) (nostr link)
```
AsciiDoc with wikilinks:
```asciidoc
Protocol Documentation
See [[Event Structure]] for the basic format, and
[[relay-docs:Implementation]] for relay-specific details.
Traditional AsciiDoc cross-refs still work: <<event-structure>>.
```
Wikitext:
```wikitext
API Reference ==
The [[Authentication]] system works with [[user-management:Profiles]].
Traditional wikitext links: [https://example.com External Site]
```
## Security Considerations
- Clients must sanitize HTML content to prevent XSS attacks
- Private spaces should use proper encryption for sensitive content
- Cross-references should be validated to prevent injection attacks
- File uploads (if supported) should be handled through NIP-96
## Rationale
### Addressing NIP-54's Critical Flaw
NIP-54's most significant issue was the breaking change from Markdown to AsciiDoc, which:
- Rendered hundreds of existing articles unusable overnight
- Created a high barrier to entry for new contributors
- Violated the principle of backwards compatibility
- Forced communities to choose between losing content or extensive migration work
### This NIP's Solution
Format Agnosticism: By supporting multiple markup formats, this NIP ensures that:
- No existing content becomes obsolete due to format changes
- Communities can choose their preferred markup language
- Migration is optional, not mandatory
- Mixed environments can coexist during transition periods
### Additional Improvements
Beyond solving the compatibility crisis, this NIP provides:
- Better organization through explicit documentation spaces
- Hierarchical structure for complex documentation projects
- Access control for private or sensitive documentation
- Universal wikilinks that work consistently across all formats
- Start pages for better user experience and navigation
- Cross-space linking for interconnected documentation projects
### Design Principles
1. Backwards Compatibility First: Never break existing content
2. Format Freedom: Let communities choose their preferred markup
3. Consistent Linking: Universal wikilink syntax across all formats
4. Gradual Migration: Support coexistence of old and new systems
5. User Experience: Prioritize ease of use and navigation
The multi-format approach allows communities to use their preferred markup while maintaining interoperability through standardized linking mechanisms and consistent event structures.
