DragonWisdom

Create HTML documentation files that are AI-agent friendly, semantically optimized, and token-efficient, while also providing a clear, visually structured presentation designed to communicate information effectively to human readers.

The Idea Behind It

Anthropic proposed moving away from Markdown files toward HTML files in order to provide more structured information in repositories.

However, this is not a simple or self-evident decision. Compared to Markdown, HTML has both advantages and disadvantages.

Pros

• Semantic HTML improves how AI agents understand and process information.
• More information can be presented in a visually structured, human-friendly way.
• HTML enables many more presentation features. For example, GitHub supports Mermaid natively in Markdown, which is useful. With HTML, however, you can provide exactly the features you need to present your information in the best possible way.

Cons of the Idea Normally

• Token usage can increase significantly, especially when using tools such as Tailwind CSS, which can make HTML very verbose.
• Writing HTML manually is not as easy as writing Markdown.

The Solution

To address these drawbacks, I researched an AI-first solution: documentation that is optimized for AI agents without compromising the reading experience for humans.

• The HTML uses only the minimum elements needed for clear semantics and reduced token usage.
• Tailwind CSS is used as the foundation for styling, but it is abstracted into custom CSS.
• Powerful human-focused features, such as sortable tables, Save button and Mermaid support, are available as opt-in features.
• JavaScript is entirely optional.

How to Use It

Store the File

Visit https://dragonwisdom.de, press Ctrl+S, or click Save, then save and use the file.

Skill

Soon, there will be a skill that makes it easy to write and update pages with AI agents.

Use It Manually

1. Reference the CSS: <link rel="stylesheet" href="https://releases.dragonwisdom.de/1.0.0/dragonwisdom.css">
2. Reference the JavaScript (optional): <script src="https://releases.dragonwisdom.de/1.0.0/dragonwisdom.js"></script>
3. Write the HTML as described in the documentation at https://dragonwisdom.de/

Headings

First-level heading

Second-level heading

Third-level heading

Fourth-level heading

Fifth-level heading

Sixth-level heading

Body Text

A paragraph forms a simple text section.

Important text and bold text can be marked up differently.

Emphasized text and italic text show semantic and typographic italics.

Marked text, small text, code and HTML add short inline examples.

Quote

Good markup starts with clear meaning.

Notes

Image

Figure

References

Internal link to the text section

Relative link to the CSS version

External link to the HTML documentation

External link in a new window

Write an email

Call a phone number

Buttons

Normal Disabled

Secondary Secondary disabled

Info Info disabled

Success Success disabled

Warning Warning disabled

Error Error disabled

Unordered List

• Unordered item
• Another item
• Final item

Ordered List

1. First step
2. Second step
3. Third step

Badges

• Neutral
• Info
• Stable
• Experimental
• Deprecated

Definitions

HTML

Structure and meaning

CSS

Presentation and layout

Table

Sortable Table

Mermaid Diagram

  flowchart LR
    A[Knowledge] --> B[DragonWisdom]
    B --> C[AI-agent friendly HTML]
    B --> D[Human-friendly Design]
    B --> E[Human-friendly optional features]