Package software.amazon.smithy.docgen.writers

Class MarkdownWriter

java.lang.Object
software.amazon.smithy.utils.AbstractCodeWriter<W>
software.amazon.smithy.codegen.core.SymbolWriter<DocWriter,DocImportContainer>
software.amazon.smithy.docgen.writers.DocWriter
software.amazon.smithy.docgen.writers.MarkdownWriter
All Implemented Interfaces:
SymbolDependencyContainer
Direct Known Subclasses:
SphinxMarkdownWriter
public class MarkdownWriter extends DocWriter
Writes documentation in CommonMark format.

  • Constructor Details

    • MarkdownWriter

      public MarkdownWriter(DocImportContainer importContainer, String filename)
      Constructs a MarkdownWriter.
      Parameters:
      importContainer - this file's import container.
      filename - The full path to the file being written to.

    • MarkdownWriter

      public MarkdownWriter(String filename)
      Constructs a MarkdownWriter.
      Parameters:
      filename - The full path to the file being written to.

  • Method Details

    • writeCommonMark

      public DocWriter writeCommonMark(String commonMark)
      Description copied from class: DocWriter
      Writes documentation based on a commonmark string.

      Smithy's documentation trait is in the CommonMark format, so writers for formats that aren't based on CommonMark will need to convert the value to their format. This includes raw HTML, which CommonMark allows.

      Specified by:
      writeCommonMark in class DocWriter
      Parameters:
      commonMark - A string containing CommonMark-formatted documentation.
      Returns:
      returns the writer.

    • openHeading

      public DocWriter openHeading(String content, int level)

    • openDefinitionList

      public DocWriter openDefinitionList()
      Description copied from class: DocWriter
      Writes any context needed to open a definition list.

      A definition list is a list where each element has an emphasized title or term. A basic way to represent this might be an unordered list where the term is followed by a colon.

      This will primarily be used to list members, with the element titles being the member names, member types, and a link to those member types where applicable. It will also be used for resource lifecycle operations, which will have similar titles.

      Specified by:
      openDefinitionList in class DocWriter
      Returns:
      returns the writer.

    • closeDefinitionList

      public DocWriter closeDefinitionList()
      Description copied from class: DocWriter
      Writes any context needed to close a definition list.

      A definition list is a list where each element has an emphasized title or term. A basic way to represent this might be an unordered list where the term is followed by a colon.

      This will primarily be used to list members, with the element titles being the member names, member types, and a link to those member types where applicable. It will also be used for resource lifecycle operations, which will have similar titles.

      Specified by:
      closeDefinitionList in class DocWriter
      Returns:
      returns the writer.

    • openDefinitionListItem

      public DocWriter openDefinitionListItem(Consumer<DocWriter> titleWriter)
      Description copied from class: DocWriter
      Writes any context needed to open a definition list item.

      A definition list is a list where each element has an emphasized title or term. A basic way to represent this might be an unordered list where the term is followed by a colon.

      This will primarily be used to list members, with the element titles being the member names, member types, and a link to those member types where applicable. It will also be used for resource lifecycle operations, which will have similar titles.

      Specified by:
      openDefinitionListItem in class DocWriter
      Parameters:
      titleWriter - writes the title or term for the definition list item.
      Returns:
      returns the writer.

    • closeDefinitionListItem

      public DocWriter closeDefinitionListItem()
      Description copied from class: DocWriter
      Writes any context needed to close a definition list item.

      A definition list is a list where each element has an emphasized title or term. A basic way to represent this might be an unordered list where the term is followed by a colon.

      This will primarily be used to list members, with the element titles being the member names, member types, and a link to those member types where applicable. It will also be used for resource lifecycle operations, which will have similar titles.

      Specified by:
      closeDefinitionListItem in class DocWriter
      Returns:
      returns the writer.

    • writeAnchor

      public DocWriter writeAnchor(String linkId)
      Description copied from class: DocWriter
      Writes a linkable element to the documentation with the given identifier.

      The resulting HTML should be able to link to this anchor with #linkId.

      For example, a direct HTML writer might create a span tag with the given string as the tag's id, or modify the next emitted tag to have the given id.

      Specified by:
      writeAnchor in class DocWriter
      Parameters:
      linkId - The anchor's link identifier.
      Returns:
      returns the writer.

    • openTabGroup

      public DocWriter openTabGroup()
      Description copied from class: DocWriter
      Writes any opening context needed to form a tab group.
      Specified by:
      openTabGroup in class DocWriter
      Returns:
      returns the writer.

    • closeTabGroup

      public DocWriter closeTabGroup()
      Description copied from class: DocWriter
      Writes any context needed to close a tab group.
      Specified by:
      closeTabGroup in class DocWriter
      Returns:
      returns the writer.

    • openTab

      public DocWriter openTab(String title)
      Description copied from class: DocWriter
      Writes any context needed to open a tab.
      Specified by:
      openTab in class DocWriter
      Parameters:
      title - The title text that is displayed on the tab itself.
      Returns:
      returns the writer.

    • closeTab

      public DocWriter closeTab()
      Description copied from class: DocWriter
      Writes any context needed to close a tab.
      Specified by:
      closeTab in class DocWriter
      Returns:
      returns the writer.

    • openCodeBlock

      public DocWriter openCodeBlock(String language)
      Description copied from class: DocWriter
      Writes any context needed to open a code block.

      For example, a pure HTML writer might write an opening pre tag.

      Specified by:
      openCodeBlock in class DocWriter
      Parameters:
      language - the language of the block's code.
      Returns:
      returns the writer.

    • closeCodeBlock

      public DocWriter closeCodeBlock()
      Description copied from class: DocWriter
      Writes any context needed to close a code block.

      For example, a pure HTML writer might write a closing pre tag.

      Specified by:
      closeCodeBlock in class DocWriter
      Returns:
      returns the writer.

    • openList

      public DocWriter openList(DocWriter.ListType listType)
      Description copied from class: DocWriter
      Writes any context needed to open a list of the given type.

      For example, a raw HTML writer might write an opening ul tag for an unordered list or an ol tag for an ordered list.

      Specified by:
      openList in class DocWriter
      Parameters:
      listType - The type of list to open.
      Returns:
      returns the writer.

    • closeList

      public DocWriter closeList(DocWriter.ListType listType)
      Description copied from class: DocWriter
      Writes any context needed to close a list of the given type.

      For example, a raw HTML writer might write a closing ul tag for an unordered list or an ol tag for an ordered list.

      Specified by:
      closeList in class DocWriter
      Parameters:
      listType - The type of list to close.
      Returns:
      returns the writer.

    • openListItem

      public DocWriter openListItem(DocWriter.ListType listType)
      Description copied from class: DocWriter
      Writes any context needed to open a list item of the given type.

      For example, a raw HTML writer might write an opening li tag for a list of any type.

      Specified by:
      openListItem in class DocWriter
      Parameters:
      listType - The type of list the item is a part of.
      Returns:
      returns the writer.

    • closeListItem

      public DocWriter closeListItem(DocWriter.ListType listType)
      Description copied from class: DocWriter
      Writes any context needed to close a list item of the given type.

      For example, a raw HTML writer might write a closing li tag for a list of any type.

      Specified by:
      closeListItem in class DocWriter
      Parameters:
      listType - The type of list the item is a part of.
      Returns:
      returns the writer.

    • toString

      public String toString()
      Description copied from class: AbstractCodeWriter
      Gets the contents of the generated code.

      The result will have an appended newline if the AbstractCodeWriter is configured to always append a newline. A newline is only appended in these cases if the result does not already end with a newline.

      Overrides:
      toString in class AbstractCodeWriter<DocWriter>
      Returns:
      Returns the generated code.

    • openAdmonition

      public DocWriter openAdmonition(DocWriter.NoticeType type, Consumer<DocWriter> titleWriter)
      Description copied from class: DocWriter
      Opens an admonition with a custom title.

      An admonition is an emphasized callout that typically have color-coded severity. A warning admonition, for example, might have a yellow or red banner that emphasizes the importance of the body text.

      Specified by:
      openAdmonition in class DocWriter
      Parameters:
      type - The type of admonition to open.
      titleWriter - A consumer that writes out the title.
      Returns:
      returns the writer.

    • openAdmonition

      public DocWriter openAdmonition(DocWriter.NoticeType type)
      Description copied from class: DocWriter
      Opens an admonition with a default title.

      An admonition is an emphasized callout that typically have color-coded severity. A warning admonition, for example, might have a yellow or red banner that emphasizes the importance of the body text.

      Specified by:
      openAdmonition in class DocWriter
      Parameters:
      type - The type of admonition to open.
      Returns:
      returns the writer.

    • closeAdmonition

      public DocWriter closeAdmonition()
      Description copied from class: DocWriter
      Closes the body of an admonition.
      Specified by:
      closeAdmonition in class DocWriter
      Returns:
      returns the writer.

    • writeBadge

      public DocWriter writeBadge(DocWriter.NoticeType type, String text)
      Description copied from class: DocWriter
      Writes text as a badge.

      Implementations SHOULD write inline.

      A badge in this context means text enclosed in a color-coded rectangular shape. The color should be based on the given type.

      Specified by:
      writeBadge in class DocWriter
      Parameters:
      type - The notice type of the badge that determines styling.
      text - The text to put in the badge.
      Returns:
      returns the writer.