ref-markdown-documentation-standards

Documentation Standards

JSON/JSON5 Code Blocks in Markdown

1. Use only ASCII characters in JSON/JSON5 code blocks: JSON examples in markdown files must contain only ASCII characters (character codes 0-127). Do not use emoji or other non-ASCII Unicode characters (such as ✅, ❌, ⚠️) within JSON/JSON5 code blocks, even in comments.

   Rationale: Users copy-paste these examples into configuration files. Many JSON parsers and text editors have issues with non-ASCII characters, leading to parsing errors.

   Correct:

   // community/sessions/local_dev.json
   {
     "host": "localhost",
     "port": 10000,
     "auth": {
       "credentials": {
         "type": "psk",
         "token": "${env:DH_AUTH_TOKEN}"  // RECOMMENDED: source the token from an env var
       }
     }
   }
   

   Incorrect:

   // community/sessions/local_dev.json
   {
     "host": "localhost",
     "port": 10000,
     "auth": {
       "credentials": {
         "type": "psk",
         "token": "${env:DH_AUTH_TOKEN}"  // ✅ RECOMMENDED: source the token from an env var
       }
     }
   }
   

2. **Use json5 for code blocks with comments**: If a JSON code block contains comments (// or /* */), mark it asjson5, not ```json. Standard JSON does not support comments.

   Correct:

   // This is a valid JSON5 comment
   {
     "key": "value"  // Inline comment
   }
   

   Incorrect:

   // This will cause a parser error
   {
     "key": "value"
   }
   

3. Validate JSON blocks: All code blocks marked as ```json must be valid, parseable JSON. Use a JSON validator to verify examples before committing.

General Documentation Standards

1. Keep examples copy-paste ready: All code examples should work when copied directly from documentation without modification (except for placeholder values like passwords, URLs, etc.).

2. Use clear placeholder values: Make it obvious what values need to be replaced:

   • Good: "password": "your-password-here", "host": "your-server.example.com"
   • Bad: "password": "xxxx", "host": "server"