image directive

[Mpdreamz]

Image

Kind	Link
Reference	https://mystmd.org/guide/directives#directive-figure
Documentation	https://mystmd.org/guide/figures#image-directive

Implementation

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

Specification compliance:

• Argument (string)
  • The filename of an image (e.g. my-fig.png)
  • Or an ID of a Jupyter Notebook cell (e.g. #my-cell).
    Pending discussion on embed directive #11 to see if we need to support id references
• Options
  • label, name (string) - Label the figure to be cross-referenced or explicitly linked to.
  • enumerated, numbered (boolean) - Turn on/off the numbering for the specific figure
  • enumerator, number (string) - Explicitly set the figure number
  • class, figclass (string)
  • height, h (string) - The figure height, in CSS units, for example 4em or 300px.
  • width, w (string) - The figure width, in CSS units, for example 50% or 300px.
  • alt (string) - Alternative text for the image
  • align (string) - The alignment of the image in the figure. Choose one of left, center or right
  • title (string) -Title text for the image

[KOTungseth]

I don't have anything for images specifically, but I do have notes for icons.

Purpose

Enhance visual clarity: Icons provide visual cues that help users quickly identify important information or actions. For example, a warning icon may highlight a critical error or caution, making it stand out immediately within the text.

Convey meaning at a glance: Icons communicate meaning quickly and efficiently. Without reading the full text, users can grasp the context or nature of the information, such as identifying a "tip" or a "note" section through a simple icon.

Improve readability: By breaking up text with recognizable symbols, inline icons make dense technical documentation easier to read. They help guide users through complex information, improving overall usability.

Standardize information presentation: Icons offer a consistent way to mark certain types of content, such as warnings, instructions, or best practices. This consistency helps users navigate the documentation more efficiently, as they become familiar with what specific icons represent.

Enhance accessibility: For visual learners, inline icons make it easier to grasp concepts. The combination of text and icons can cater to different learning styles, enhancing accessibility and comprehension.

Indicate actions or interactivity: Icons can signal where users need to perform an action (e.g., a gear icon for settings or a link icon for external references). This improves the overall flow by pointing users to actionable items.

Create a user-friendly experience: The use of icons introduces a visual element to documentation, making it more engaging and easier to navigate. It provides a more user-centric design, which is especially helpful in lengthy or technical content.

Best practice

Avoid overwhelming users with too many different icons. Use a small set of well-defined icons to represent common concepts or actions, which helps maintain focus and reduces cognitive load.