Skip to content
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

Closed
9 of 32 tasks
Tracked by #2
Mpdreamz opened this issue Nov 6, 2024 · 2 comments · Fixed by #64
Closed
9 of 32 tasks
Tracked by #2

admonition directive #3

Mpdreamz opened this issue Nov 6, 2024 · 2 comments · Fixed by #64
Labels
authoring Relates to our markdown parser

Comments

@Mpdreamz
Copy link
Member

Mpdreamz commented Nov 6, 2024

Admonitions

Callouts, or “admonitions”, highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning.

Kind Link
Reference https://mystmd.org/guide/directives#directive-admonition
Documentation https://mystmd.org/guide/admonitions

Implementation

  • Parses directives and aliases
  • Emits HTML
  • Unit tests
  • Validation (emits, warnings and errors).

Specification compliance:

  • Arguments is parsed
  • Body is parsed
  • Options:
    • 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 admonition
    • enumerator, number (string) - Explicitly set the admonition number
    • class (string) - CSS classes to add to your admonition. Special classes include:
      • dropdown - turns the admonition into a <details> html element
      • simple - an admonition with “simple” styles
      • the name of an admonition (if no directive alias is used)
    • icon (boolean) - Setting icon to false will hide the icon.
    • open (boolean) - Turn the admonition into a dropdown, and set the open state.
  • Aliases:
    • attention
    • caution
    • danger
    • error
    • important
    • hint
    • note
    • seealso
    • tip
    • warning
    • .callout-note
    • .callout-warning
    • .callout-important
    • .callout-tip
    • .callout-caution
@Mpdreamz Mpdreamz added enhancement authoring Relates to our markdown parser labels Nov 6, 2024
@bmorelli25
Copy link
Member

bmorelli25 commented Nov 7, 2024

Something else to consider on the topic of admonitions — cc @KOTungseth

@KOTungseth
Copy link

Context: elastic-docs-v3/issues/4

I'm also including my own notes ⬇️

Purpose

Highlight 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.

Required

Warning: 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 practice

Use admonitions judiciously. Overloading documentation with admonitions can dilute their effectiveness and overwhelm users. Reserve them for genuinely important information.

@Mpdreamz Mpdreamz linked a pull request Nov 13, 2024 that will close this issue
Mpdreamz pushed a commit that referenced this issue Jan 5, 2025
### 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"
/>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
authoring Relates to our markdown parser
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants