Special Characters & Edge Cases

This guide covers how EmberDocs handles special characters and unusual document structures.

Filename Handling

Valid Filenames

EmberDocs supports filenames with:

✓ kebab-case: my-document.md
✓ numbers: guide-123.md
✓ underscores: my_document.md
✓ numbers-and-hyphens: api-v2-docs.md

Special Characters to Avoid

Recommended Naming Convention

Use lowercase with hyphens (kebab-case):

✓ good: advanced-features.md
✓ good: api-reference.md
✓ good: getting-started-guide.md
✗ bad: AdvancedFeatures.md
✗ bad: api_reference.md
✗ bad: Getting Started Guide.md

Slug Structure

The slug field in frontmatter defines the document URL:

---
title: "Advanced Features"
slug: "guides/advanced-features"  # becomes /docs/guides/advanced-features
---

Slug Generation

The generateSlug() function creates URL-safe slugs from text:

// Examples
generateSlug('Getting Started');     // "getting-started"
generateSlug('API & Reference');    // "api-and-reference"
generateSlug('Hello World!');       // "hello-world"
generateSlug('Special-Chars_123');  // "special-chars123"

Behavior:

• Converts to lowercase
• Replaces & with and
• Removes special characters (keeps alphanumeric, spaces, hyphens)
• Replaces spaces with hyphens
• Trims leading/trailing hyphens

Note: Frontmatter slug fields are used as-is in URLs. For heading IDs, generateSlug() is used automatically.

Content Edge Cases

Unicode & International Characters

Markdown content (not filenames) supports full Unicode:

# 你好 (Hello in Chinese)

This document uses émojis: 🎉 🚀 ✨

### Ñoño (Spanish special chars)

All render correctly with proper charset=utf-8 in HTML head.

Code Block Edge Cases

Empty Code Blocks

Empty blocks render correctly with no errors.

Unspecified Language

This is a code block without a language identifier.
It renders in default monospace styling.

Unknown Language

This uses an unsupported language.
It falls back to plain text rendering.

Very Long Lines

const veryLongFunctionNameThatGoesOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOnAndOn = () => {};

Horizontal scroll handles this gracefully.

Heading Edge Cases

Special Characters in Headings

# API Documentation (v2.0)
## Using @decorators
### Functions & Methods

All render correctly and are included in table of contents.

Very Long Headings

The TOC and page handle this without breaking.

Link Edge Cases

Absolute vs Relative Links

[Absolute](/docs/guides/basic-usage)
[Relative](../guides/basic-usage)
[External](https://example.com)
[With Fragment](/docs/api-reference/configuration#environment-setup)

All link types work correctly in navigation context.

Broken Links

If a linked document doesn't exist:

• Development mode: Shows warning in console
• Production: Link renders but targets 404 page

Metadata Edge Cases

Missing Fields

Missing optional fields don't break the document:

---
title: "Minimal Document"
slug: "minimal"
---

Optional fields (author, date, tags, order) default to sensible values.

Invalid Date Format

---
title: "Document"
slug: "doc"
date: "not a date"  # Invalid
---

Invalid dates are skipped; frontmatter still parses correctly.

Large Documents

EmberDocs handles large documents:

Performance remains good even with very large documents.

Many Tags

---
tags: [
  "documentation",
  "guides",
  "api",
  "reference",
  "tutorial",
  "advanced",
  "intermediate",
  "beginner",
  "examples"
]
---

Tag arrays of any size work correctly.

Table Edge Cases

Simple Table

Wide Table

Horizontal scroll handles overflow.

Table with Special Characters

All render correctly.

List Edge Cases

Deeply Nested Lists

• Level 1
  • Level 2
    • Level 3
      • Level 4
        • Level 5
          • Level 6

Nesting to any depth works without breaking.

Mixed List Types

1. Ordered item
   • Unordered sub-item
   • Another unordered
2. Next ordered
   • Sub-item
3. Final ordered

Mixed nesting renders correctly.

Large Lists

EmberDocs handles lists with:

• 10s of items
• 100s of items
• 1000s of items (though very long lists should be paginated for UX)

HTML in Markdown

Raw HTML in markdown:

<div class="custom">
  <p>This HTML is preserved</p>
</div>

HTML is rendered as-is in the content.

Script Tags

Script tags in markdown are handled by react-markdown, which renders them as text by default. For security, you should not include script tags in markdown content.

Note: react-markdown does not execute scripts, but they may render as visible text. Avoid including script tags in documentation content.

Performance Edge Cases

Many Documents

EmberDocs is designed to handle:

• 100+ documents efficiently
• 1000+ documents with good performance
• Larger document sets (performance may vary based on content size)

Large Search Index

Search index size depends on document count and content:

• Index is pre-built at build time
• Stored as JSON in public/search-index.json
• FlexSearch index is built client-side from the serialized documents
• No runtime build penalty (index is loaded once on page load)

Image Handling

Images in markdown are rendered as standard <img> tags:

![Alt text](./image.webp)
![Alt text](./image.png)

Note: For optimal performance, optimize images before including them in documentation. Large images may impact page load times.

Troubleshooting Edge Cases

Document Not Found

Symptom: 404 when visiting document Check:

• Slug matches file path
• File uses .md extension
• Frontmatter is valid YAML

# Valid structure
file: docs/examples/guides/basic-usage.md
slug: "guides/basic-usage"
url: /docs/guides/basic-usage

Character Encoding Issues

Symptom: Special characters display as ? or corrupted Check:

• File saved as UTF-8
• HTML head includes: <meta charset="utf-8">
• No BOM (Byte Order Mark) in file

TOC Not Updating

Symptom: Table of contents doesn't highlight active section Check:

• Headings have id attributes (auto-added)
• JavaScript enabled in browser
• IntersectionObserver supported

Best Practices Summary

1. Filenames: Use lowercase with hyphens
2. Slugs: Match file path, keep simple
3. Content: Use standard Markdown
4. Tables: Keep reasonable width
5. Images: Optimize before including
6. Lists: Nest to 5 levels max
7. Code: Use proper language tags
8. Links: Use absolute paths in docs

See Also:

• Basic Usage
• Advanced Features
• Configuration