-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
admonition directive #3
Comments
Something else to consider on the topic of admonitions — cc @KOTungseth |
Context: elastic-docs-v3/issues/4 I'm also including my own notes ⬇️ PurposeHighlight important information: Admonitions draw attention to specific content that may require special attention, such as warnings, tips, notes, or important instructions. This ensures critical information stands out from the main text. Convey urgency or caution: Admonitions are often used to alert users to potential risks, such as system warnings, common pitfalls, or security issues. They prevent mistakes by clearly marking these sections as something to be cautious about. Provide additional context: They can offer extra insights, best practices, or useful tips that enhance the user's understanding. These sections are often optional but valuable for users who want more context without disrupting the flow of the primary content. Improve readability: By visually differentiating certain content, admonitions make the documentation more scannable. Users can quickly identify crucial information (like warnings or recommendations) while skimming through the document. Enhance user experience: Admonitions break up dense technical content and create a more engaging and interactive reading experience. They often use icons or colored boxes to signal specific meanings (e.g., warnings in red, notes in blue). Organize content: Admonitions help structure information by grouping related content under recognizable labels like "Warning," "Note," or "Tip." This helps users process information more efficiently and find what they need faster. RequiredWarning: This admonition highlights potential hazards or risks that could lead to significant issues, such as data loss, system failure, or security vulnerabilities. It alerts users to exercise caution and take specific actions to avoid problems. Note: This type of admonition provides important additional information that users should be aware of. It may clarify a point, offer helpful context, or highlight considerations that could enhance understanding or usability. Tip: Tips offer practical advice or best practices that can help users achieve better results or avoid common pitfalls. They provide suggestions that are not critical but can improve the user experience or efficiency. Caution: This admonition indicates a situation that may lead to minor problems or errors if not handled properly. It encourages users to be mindful and take precautions to prevent these issues. Best practiceUse admonitions judiciously. Overloading documentation with admonitions can dilute their effectiveness and overwhelm users. Reserve them for genuinely important information. |
### Summary Per #106 (comment), supported admonition types should be `Note`, `Warning`, `Important`, and `Tip`. This list was determined after analyzing supported admonitions in our current Asciidoc system and cross-referencing with our style guide. This PR removes support for `Caution` and `Attention` and replaces them with support for `Warning` and `Important`. It also adds a missing `AdmonitionUnsupportedTest`. I've updated #3 to reflect these supported admonition types as that issue is referenced in the error logs. ### Results Tested locally with: ``` dotnet publish "src/docs-builder/docs-builder.csproj" -c Release -o .artifacts/publish \ --self-contained true /p:PublishTrimmed=true /p:PublishSingleFile=false /p:PublishAot=true -a arm64 ./.artifacts/publish/docs-builder serve ``` <img width="625" alt="Screenshot 2025-01-03 at 10 25 37 PM" src="https://github.com/user-attachments/assets/52fd3419-194f-4903-b368-724d6389e28c" /> <img width="632" alt="Screenshot 2025-01-03 at 10 25 32 PM" src="https://github.com/user-attachments/assets/7419fff1-6d4f-4177-9c8e-7a836a9591ed" />
Admonitions
Implementation
Specification compliance:
label, name
(string) - Label the admonition to be cross-referenced or explicitly linked to.enumerated, numbered
(boolean) - Turn on/off the numbering for the specific admonitionenumerator, number
(string) - Explicitly set the admonition numberdropdown
- turns the admonition into a<details>
html elementsimple
- an admonition with “simple” stylesicon
(boolean) - Setting icon to false will hide the icon.The text was updated successfully, but these errors were encountered: