@oxide/react-asciidoc 0.0.1-alpha.2 → 0.0.1-alpha.20

package/dist/types/examples/writersGuide.d.ts

@@ -0,0 +1,2 @@
+export default writersGuide;
+declare const writersGuide: "\n// View this document online at https://asciidoctor.org/docs/asciidoc-writers-guide/\n= AsciiDoc Writer's Guide\nDan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>\n:description: This guide describes the basic structure of an AsciiDoc document, how to create your first AsciiDoc document, how to add other structural elements such as lists, block quotes and source code, and how to convert an AsciiDoc document to HTML, DocBook and PDF.\n:keywords: AsciiDoc, Asciidoctor, syntax, reference, learn, how to, writers, authors\n:page-description: {description}\n:page-keywords: {keywords}\n:page-layout: docs\nifndef::env-site[]\n:toc: left\n:icons: font\n:idprefix:\n:idseparator: -\n:sectanchors:\n:source-highlighter: highlightjs\nendif::[]\n:experimental:\n:mdash: &#8212;\n:language: asciidoc\n:source-language: {language}\n:table-caption!:\n:example-caption!:\n:figure-caption!:\n:imagesdir: ../images\n// Refs\n:url-docs-asciidoc: https://docs.asciidoctor.org/asciidoc/latest/\n:url-quickref: {url-docs-asciidoc}syntax-quick-reference/\n:user-ref: https://asciidoctor.org/docs/user-manual\n:asciidoctor-ref: https://asciidoctor.org/\n:asciidoctor-gem-ref: https://rubygems.org/gems/asciidoctor\n:uri-install: https://asciidoctor.org/docs/install-toolchain/\n:fopub-doc-ref: https://github.com/asciidoctor/asciidoctor-fopub#readme\n:docs-ref: https://asciidoctor.org/docs\n:gist-ref: https://gist.github.com\n:snippets-ref: https://gitlab.com/explore/snippets\n:publican-ref: https://fedorahosted.org/publican\n\nThis guide provides a gentle introduction to AsciiDoc, a _plain text_ documentation *syntax* and *processor*.\nThis introduction is intended for anyone who wants to reduce the effort required to write and publish content, whether for technical documentation, articles, web pages or good ol'-fashioned prose.\n\nTIP: If you want to know what AsciiDoc is all about, find the answer in {url-docs-asciidoc}#about-asciidoc[About AsciiDoc].\nIf you're looking for a concise survey of the AsciiDoc syntax, consult the {url-quickref}[AsciiDoc Syntax Quick Reference].\n\nIn this guide, you'll learn:\n\n- The basic structure of an AsciiDoc document\n- How to create your first AsciiDoc document\n- How to add other structural elements such as lists, block quotes and source code\n- How to convert an AsciiDoc document to HTML, DocBook and PDF\n\nIn addition to covering the AsciiDoc basics, this guide also suggests a set of conventions to help you create more consistent documents and maximize your writing productivity.\n\nLet's dive in to AsciiDoc!\n\n== Writing in AsciiDoc\n\nThe goal of this section is to teach you how to compose your first AsciiDoc document.\nHopefully, when you look back, you'll agree it just makes sense.\n\nYour adventure with AsciiDoc begins in your favorite text editor.\n\n=== It's just text, mate.\n\nSince AsciiDoc syntax is just _plain text_, you can write an AsciiDoc document using _any_ text editor.\nYou don't need complex word processing programs like Microsoft Word, OpenOffice Writer or Google Docs.\nIn fact, you _shouldn't_ use these programs because they add cruft to your document (that you can't see) and makes conversion tedious.\n\nTIP: While it's true any text editor will do, I recommend selecting an editor that supports syntax highlighting for AsciiDoc.\nThe *[red]##c##[green]##o##[purple]##l##[fuchsia]##o##[blue]##r##* brings contrast to the text, making it easier to read.\nThe highlighting also confirms when you've entered the correct syntax for an inline or block element.\n\nThe most popular application for editing plain text on macOS is *TextMate*.\nA similar choice on Linux is *GEdit*.\nOn Windows, stay away from Notepad and Wordpad because they produce plain text which is not cross-platform friendly.\nOpt instead for a competent text editor like *Notepad++*.\nIf you're a programmer (or a writer with an inner geek), you'll likely prefer *Vim*, *Emacs*, or *Sublime Text*, all of which are available cross-platform.\nThe key feature all these editors share is syntax highlighting for AsciiDoc.\n\nOpen up your favorite text editor and get ready to write some AsciiDoc!\n\n=== Content is king!\n\nThe bulk of the content in a document is paragraph text.\nThis is why Asciidoctor doesn't require any special markup or attributes to specify paragraph content.\nYou can just start typing.\n\nIn Asciidoctor, adjacent or consecutive lines of text form a paragraph element.\nTo start a new paragraph after another element, such as a section title or table, hit the kbd:[RETURN] key twice to insert a blank line, and then continue typing your content.\n\n.Two paragraphs in an AsciiDoc document\n[source]\n----\nThis journey begins one late Monday afternoon in Antwerp.\nOur team desperately needs coffee, but none of us dare open the office door.\n\nTo leave means code dismemberment and certain death.\n----\n\n.The two paragraphs rendered using the default (html5) converter and stylesheet (asciidoctor.css)\n====\nThis journey begins one late Monday afternoon in Antwerp.\nOur team desperately needs coffee, but none of us dare open the office door.\n\nTo leave means code dismemberment and certain death.\n====\n\nJust like that, *you're writing in AsciiDoc!*\nAs you can see, it's just like writing an e-mail.\n\nSave the file with a file extension of .adoc.\n\nTIP: If you want to find out how to convert the document to HTML, DocBook or PDF, skip ahead to the section on <<converting-your-document>>.\n\n==== Wrapped text and hard line breaks\n\nSince adjacent lines of text are combined into a single paragraph when Asciidoctor converts a document, that means you can wrap paragraph text or put each sentence or phrase on a separate line.\nThe line breaks won't appear in the output.\n\nHowever, if you want the line breaks in a paragraph to be preserved, you can either use a space followed by a plus sign ({plus}) or set the hardbreaks option on the paragraph.\nThis results in a visible line break (e.g., <br>) following each line.\n\n[source]\n.Line breaks preserved using a space followed by the plus sign ({plus})\n----\nRubies are red, +\nTopazes are blue.\n----\n\n====\nRubies are red, +\nTopazes are blue.\n====\n\n[source]\n.Line breaks preserved using the hardbreaks option\n----\n[%hardbreaks]\nRuby is red.\nJava is black.\n----\n\n====\n[%hardbreaks]\nRuby is red.\nJava is black.\n====\n\nTo preserve line breaks throughout your whole document, add the hardbreaks attribute to the document's header.\n\n.Line breaks preserved throughout the document using the hardbreaks attribute\n[source]\n----\n= Line Break Doc Title\n:hardbreaks:\n\nRubies are red,\nTopazes are blue.\n----\n\n=== Admonitions\n\nThere are certain statements you may want to draw attention to by taking them out of the content's flow and labeling them with a priority.\nThese are called admonitions.\nIt's rendered style is determined by the assigned label (i.e., value).\nAsciidoctor provides five admonition style labels:\n\n* NOTE* TIP* IMPORTANT* CAUTION* WARNING\n.Caution vs. Warning\n[#caution-vs-warning]\n****\nWhen choosing the admonition type, you may find yourself getting confused between \"caution\" and \"warning\" as these words are often used interchangeably.\nHere's a simple rule to help you differentiate the two:\n\n* Use *CAUTION* to advise the reader to _act_ carefully (i.e., exercise care).\n* Use *WARNING* to inform the reader of danger, harm, or consequences that exist.\n\nTo find a deeper analysis, see https://www.differencebetween.com/difference-between-caution-and-vs-warning/.\n****\n\nWhen you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use.\nThe label must be uppercase and followed by a colon (:).\n\n.Admonition paragraph syntax\n[source]\n----\nWARNING: Wolpertingers are known to nest in server racks. <1> <2>\nEnter at your own risk.\n----\n<1> The label must be uppercase and immediately followed by a colon (:).\n<2> Separate the first line of the paragraph from the label by a single space.\n\n.Result: Admonition paragraph\n====\nWARNING: Wolpertingers are known to nest in server racks.\nEnter at your own risk.\n====\n\nAn admonition paragraph is rendered in a callout box with the admonition label--or its corresponding icon--in the gutter.\nIcons are enabled by setting the icons attribute on the document.\n\nNOTE: Admonitions can also encapsulate any block content, which we'll cover later.\n\n=== Mild punctuation, strong impact\n\nJust as we emphasize certain words and phrases when we speak, we can emphasize them in text by surrounding them with punctuation.\nAsciiDoc refers to this markup as _quoted text_.\n\n==== Quoted text\n\nFor instance, in an e-mail, you might \"speak\" a word louder by enclosing it in asterisks.\n\n[source]\nI can't believe it, we *won*!\n\nAs you would expect, the asterisks make the text *won* bold.\nYou can almost sense the emotion.\nThis is one example of quoted (i.e., formatted) text.\n\nNOTE: The term \"quote\" is used liberally here to apply to any symbols that surround text in order to apply emphasis or special meaning.\n\nHere are the forms of quoted text that AsciiDoc recognizes:\n\n.Bold, italic, and monospace formatting syntax\n[source]\n----\nbold *constrained* & **un**constrained\n\nitalic _constrained_ & __un__constrained\n\nbold italic *_constrained_* & **__un__**constrained\n\nmonospace constrained & \\un\\constrained\n\nmonospace bold *constrained* & \\**un**\\constrained\n\nmonospace italic _constrained_ & \\__un__\\constrained\n\nmonospace bold italic *_constrained_* & \\**__un__**\\constrained\n----\n\nWhen you want to quote text (e.g., place emphasis) somewhere other than at the boundaries of a word, you need to double up the punctuation.\n\n.Result: Bold, italic, and monospace text\n====\nbold *constrained* & **un**constrained\n\nitalic _constrained_ & __un__constrained\n\nbold italic *_constrained_* & **__un__**constrained\n\nmonospace constrained & \\un\\constrained\n\nmonospace bold *constrained* & \\**un**\\constrained\n\nmonospace italic _constrained_ & \\__un__\\constrained\n\nmonospace bold italic *_constrained_* & \\**__un__**\\constrained\n====\n\nAny quoted text can be prefixed with an attribute list.\nThe first positional attribute is treated as a role.\nThe role can be used to apply custom styling to the text.\nFor instance:\n\n[source]\nType the word [.userinput]#asciidoc# into the search bar.\n\nWhen converting to HTML, the word \"asciidoc\" is wrapped in <span> tags and the role is used as the element's CSS class:\n\n[source,xml]\n<span class=\"userinput\">asciidoc</span>\n\nYou can apply styles to the text using CSS.\n\nYou may not always want these substitutions to take place.\nIn those cases, you'll need to use markup to escape the text.\n\n==== Preventing substitution\n\nIf you are getting quoted text behavior where you don't want it, you can use a backslash or a passthrough macro to prevent it.\n\nAsciidoctor provides several approaches for preventing substitutions.\n\n.Backslash escaping\nTo prevent punctuation from being interpreted as formatting markup, precede it with a backslash (\\).\nIf the formatting punctuation begins with two characters (e.g., +__+), you need to precede it with two backslashes (+\\+).\nThis is also how you can prevent character and attribute references from substitution.\nWhen your document is processed, the backslash is removed so it doesn't display in your output.\n\n[source]\n----\n*Stars* will appear as *Stars*, not as bold text.\n\n&sect; will appear as an entity, not the &sect; symbol.\n\n\\__func__ will appear as __func__, not as emphasized text.\n\n{two-semicolons} will appear {two-semicolons}, not resolved as ;;.\n----\n\nAsciidoctor supports several forms of the passthrough macro.\n\ninline pass macro:: An inline macro named pass that can be used to passthrough content.\nSupports an optional set of substitutions.\n+\n[source]\n----\npass:[content like #{variable} passed directly to the output] followed by normal content.\n\ncontent with only select substitutions applied: pass:c,a[__<{email}>__]\n----\n\nsingle and double plus:: A special syntax for preventing text from being formatted.\nOnly escapes special characters for compliance with the output format and doesn't support explicit substitutions.\n\ntriple plus:: A special syntax for designating passthrough content.\nDoes not apply any substitutions (equivalent to the inline pass macro) and doesn't support explicit substitutions.\n\ndouble dollar (deprecated):: A deprecated special syntax for designating passthrough content.\nLike the triple plus, does not apply any substitutions and doesn't support explicit substitutions.\n\nCAUTION: Asciidoctor does not implement the block pass macro.\nInstead, you should use a <<pass-blocks,pass block>>.\n\n==== Inline pass macro and explicit substitutions\n\nTo exclude a phrase from substitutions and disable escaping of special characters, enclose it in the inline pass macro.\nFor example, here's one way to format text as underline when generating HTML from AsciiDoc:\n\n[source]\n----\nThe text pass:[<u>underline me</u>] is underlined.\n----\n\n====\nThe text pass:[<u>underline me</u>] is underlined.\n====\n\nIf you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.\n\n------\n[subs=+macros] <1>\n----\nI better not contain *bold* or _italic_ text.\npass:quotes[But I should contain *bold* text.] <2>\n----\n------\n<1> macros is assigned to subs, which allows any macros within the block to be processed.\n<2> The pass macro is assigned the quotes value. Text within the square brackets will be formatted.\n\nThe inline pass macro does introduce additional markup into the source code that could make it invalid in raw form.\nHowever, the output it produces will be valid when viewed in a viewer (HTML, PDF, etc.).\n\n====\n[subs=+macros]\n----\nI better not contain *bold* or _italic_ text.\npass:quotes[But I should contain *bold* text.]\n----\n====\n\nThe inline pass macro also accepts shorthand values for specifying substitutions.\n\n* c = special characters\n* q = quotes\n* a = attributes\n* \r = replacements\n* m = macros\n* p = post replacements\n\nFor example, the quotes text substitution value is assigned in the inline passthrough macro below:\n\n[source]\n----\nThe text pass:q[<u>underline *me*</u>] is underlined and the word \"me\" is bold.\n----\n\n====\nThe text pass:q[<u>underline *me*</u>] is underlined and the word \"me\" is bold.\n====\n\n==== Triple plus passthrough\n\nThe triple-plus passthrough works much the same way as the pass macro.\nTo exclude content from substitutions, enclose it in triple pluses (pass:[+++]).\n\n +++content passed directly to the output+++ followed by normal content.\n\nThe triple-plus macro is often used to output custom HTML or XML.\n\n[source]\n----\nThe text +++<u>underline me</u>+++ is underlined.\n----\n\n====\nThe text +++<u>underline me</u>+++ is underlined.\n====\n\n.Single plus enclosure\n\nTo exclude a phrase from substitutions, enclose it in plus signs (+).\n\n[source]\n----\nThis +*literal*+ will appear as *literal*.\n----\n\n==== Replacements\n\nAsciiDoc also recognizes textual representations of symbols, arrows and dashes.\n\n[cols=\"2,^1l,^1l,^1,2\"]\n.Textual symbol replacements\n|===\n|Name |Syntax |Unicode Replacement |Rendered |Notes\n\n|Copyright\n|(C)\n|&#169;\n|(C)\n|\n\n|Registered\n|(R)\n|&#174;\n|(R)\n|\n\n|Trademark\n|(TM)\n|&#8482;\n|(TM)\n|\n\n|Em dash\n|--\n|&#8212;\n|{empty}--{empty}\n|Only replaced if between two word characters, between a word character and a line boundary, or flanked by spaces.\n\nWhen flanked by space characters (e.g., +a -- b+), the normal spaces are replaced by thin spaces (&#8201;).\n\n|Ellipsis\n|...\n|&#8230;\n|...\n|\n\n|Single right arrow\n|->\n|&#8594;\n|->\n|\n\n|Double right arrow\n|=>\n|&#8658;\n|=>\n|\n\n|Single left arrow\n|<-\n|&#8592;\n|<-\n|\n\n|Double left arrow\n|<=\n|&#8656;\n|<=\n|\n\n|Typographic apostrophe\n|Sam's\n|Sam&#8217;s\n|Sam's\n|The typewriter apostrophe is replaced with the typographic (aka curly) apostrophe.\n|===\n\nThis mild punctuation does not take away from the readability of the text.\nIn fact, you could argue that it makes the text easier to read.\nWhat's important is that these are conventions with which you are likely already familiar.\n\nPunctuation is used in AsciiDoc to create another very common type of element in documents, _lists!_\n\n=== Lists, lists, lists\n\nThere are three types of lists supported in AsciiDoc:\n\n. Unordered\n. Ordered\n. Description\n\nUnordered and ordered lists are structurally very similar.\nThey consist of items that are prefixed by different types of markers (i.e., bullet).\nIn contrast, description lists--also called variable, labeled, or term-definition lists--are collections of terms that each have their own supporting content.\nUnlike unordered and ordered lists, description lists are rarely nested, though they often contain the former.\n\nLet's explore each type of list, then mix them together.\nWe'll also look at how to put complex content inside a list item.\n\n==== Lists of things\n\nIf you were to create a list in an e-mail, how would you do it?\nChances are, you'd mark list items using the same characters that Asciidoctor uses to find list items.\n\nIn the example below, each list item is marked using an asterisk ({asterisk}), the AsciiDoc syntax specifying an unordered list item.\n\n[source]\n----\n* Edgar Allan Poe\n* Sheri S. Tepper\n* Bill Bryson\n----\n\nA list item's first line of text must be offset from the marker ({asterisk}) by at least one space.\nIf you prefer, you can indent list items.\nBlank lines are required before and after a list.\nAdditionally, blank lines are permitted, but not required, between list items.\n\n.Rendered unordered list\n====\n* Edgar Allan Poe\n* Sheri S. Tepper\n* Bill Bryson\n====\n\nYou can add a title to a list by prefixing the title with a period (.).\n\n[source]\n----\n.Kizmet's Favorite Authors\n* Edgar Allan Poe\n* Sheri S. Tepper\n* Bill Bryson\n----\n\n.Rendered unordered list with a title\n====\n.Kizmet's Favorite Authors\n* Edgar Allan Poe\n* Sheri S. Tepper\n* Bill Bryson\n====\n\nWas your instinct to use a hyphen (-) instead of an asterisk to mark list items?\nGuess what?\nThat works too!\n\n[source]\n----\n- Edgar Allan Poe\n- Sheri S. Tepper\n- Bill Bryson\n----\n\nYou should reserve the hyphen for lists that only have a single level because the hyphen marker (-) doesn't work for nested lists.\nNow that we've mentioned nested lists, let's go to the next section and learn how to create lists with multiple levels.\n\n[#separating-lists]\n.Separating Lists\n****\nIf you have adjacent lists, they have the tendency to want to fuse together.\nTo force lists apart, insert a line comment (//) surrounded by blank lines between the two lists.\nHere's an example, where the - text in the line comment indicates the line serves as an \"end of list\" marker:\n\n[source]\n----\n* Apples\n* Oranges\n\n//-\n\n* Walnuts\n* Almonds\n----\n****\n\nTo nest an item, just add another asterisk ({asterisk}) to the marker, and another for each subsequent level.\n\n[source]\n----\n.Possible DefOps manual locations\n* West wood maze\n** Maze heart\n*** Reflection pool\n** Secret exit\n* Untracked file in git repository\n----\n\n.Rendered nested, unordered list\n====\n.Possible DefOps manual locations\n* West wood maze\n** Maze heart\n*** Reflection pool\n** Secret exit\n* Untracked file in git repository\n====\n\nIn Asciidoctor 1.5.7 and earlier you could only have up to six (6) levels of nesting (assuming one level uses the hyphen marker).\n\nSince Asciidoctor 1.5.8, you can nest unordered lists to any depth.\nKeep in mind, however, that some interfaces will begin flattening lists after a certain depth.\nGitHub starts flattening list after 10 levels of nesting.\n\n[source]\n----\n* level 1\n** level 2\n*** level 3\n**** level 4\n***** level 5\n* level 1\n----\n\n====\n* level 1\n** level 2\n*** level 3\n**** level 4\n***** level 5\n* level 1\n====\n\nWhile it would seem as though the number of asterisks represents the nesting level, that's not how depth is determined.\nA new level is created for each unique marker encountered.\nHowever, it's much more intuitive to follow the convention that the number of asterisks equals the level of nesting.\nAfter all, we're shooting for plain text markup that is readable _as is_.\n\n==== Ordering the things\n\nSometimes, we need to number the items in a list.\nInstinct might tell you to prefix each item with a number, like in this next list:\n\n[source]\n----\n1. Protons\n2. Electrons\n3. Neutrons\n----\n\nThe above works, but\nsince the numbering is obvious, the AsciiDoc processor will insert the numbers for you if you omit them:\n\n[source]\n----\n. Protons\n. Electrons\n. Neutrons\n----\n\n====\n. Protons\n. Electrons\n. Neutrons\n====\n\nIf you decide to use number for your ordered list, you have to keep them sequential.\nThis differs from other lightweight markup languages.\nIt's one way to adjust the numbering offset of a list.\nFor instance, you can type:\n\n[source]\n----\n4. Step four\n5. Step five\n6. Step six\n----\n\nHowever, in general the best practice is to use the start attribute to configure this sort of thing:\n\n[source]\n----\n[start=4]\n. Step four\n. Step five\n. Step six\n----\n\nTo present the items in reverse order, add the \reversed option:\n\n[source]\n----\n[%reversed]\n.Parts of an atom\n. Protons\n. Electrons\n. Neutrons\n----\n\n====\n[%reversed]\n.Parts of an atom\n. Protons\n. Electrons\n. Neutrons\n====\n\nYou can give a list a title by prefixing the line with a dot immediately followed by the text (without leaving any space after the dot).\n\nHere's an example of a list with a title:\n\n[source]\n----\n.Parts of an atom\n. Protons\n. Electrons\n. Neutrons\n----\n\n====\n.Parts of an atom\n. Protons\n. Electrons\n. Neutrons\n====\n\nYou create a nested item by using one or more dots in front of each the item.\n\n[source]\n----\n. Step 1\n. Step 2\n.. Step 2a\n.. Step 2b\n. Step 3\n----\n\nAsciiDoc selects a different number scheme for each level of nesting.\nHere's how the previous list renders:\n\n.A nested ordered list\n====\n. Step 1\n. Step 2\n.. Step 2a\n.. Step 2b\n. Step 3\n====\n\n[TIP]\n====\nLike with the asterisks in an unordered list, the number of dots in an ordered list doesn't represent the nesting level.\nHowever, it's much more intuitive to follow this convention:\n\n[quote]\n# of dots = level of nesting\n\nAgain, we are shooting for plain text markup that is readable _as is_.\n====\n\nAsciidoctor works hard to infer the relationships between the items that are most intuitive to us humans.\nHere's an example of nesting an unordered list inside of an ordered list:\n\n[source]\n----\n. Linux\n* Fedora\n* Ubuntu\n* Slackware\n. BSD\n* FreeBSD\n* NetBSD\n----\n\n====\n. Linux\n* Fedora\n* Ubuntu\n* Slackware\n. BSD\n* FreeBSD\n* NetBSD\n====\n\nYou can spread the items out and indent the nested lists if that makes it more readable for you:\n\n[source]\n----\n. Linux\n\n\t* Fedora\n\t* Ubuntu\n\t* Slackware\n\n. BSD\n\n\t* FreeBSD\n\t* NetBSD\n----\n\nThe following table shows the numbering scheme used by default for each nesting level.\n\n.Ordered list numbering scheme by level\n[cols=\"^2,3,3,4\"]\n|===\n|Level |Numbering Scheme |Examples |CSS class (HTML converter)\n\n|1\n|Arabic\n|1. 2. 3.\n|arabic\n\n|2\n|Lower Alpha\n|a. b. c.\n|loweralpha\n\n|3\n|Lower Roman\n|i. ii. iii.\n|lowerroman\n\n|4\n|Upper Alpha\n|A. B. C.\n|upperalpha\n\n|5\n|Upper Roman\n|I. II. III.\n|upperroman\n|===\n\nYou can override the number scheme for any level by setting its style (the first positional entry in a block attribute list).\nYou can also set the starting number using the start attribute:\n\n[source]\n----\n[lowerroman, start=5]\n. Five\n. Six\n[loweralpha]\n.. a\n.. b\n.. c\n. Seven\n----\n\n==== Description lists\n\nA description list (often abbreviate as dlist) is useful when you need to include a description or supporting text for one or more terms.\nEach item in a description list consists of:\n\n* one or more terms\n* a separator following each term (typically a double colon, ::)\n* at least one space or endline\n* the supporting content (either text, attached blocks, or both)\n\nHere's an example of a description list that identifies parts of a computer:\n\n[source]\n----\nCPU:: The brain of the computer.\nHard drive:: Permanent storage for operating system and/or user files.\nRAM:: Temporarily stores information the CPU uses during operation.\nKeyboard:: Used to enter text or control items on the screen.\nMouse:: Used to point to and select items on your computer screen.\nMonitor:: Displays information in visual form using text and graphics.\n----\n\nBy default, the content of each item is displayed below the description when rendered.\nHere's a preview of how this list is rendered:\n\n.A basic description list\n====\nCPU:: The brain of the computer.\nHard drive:: Permanent storage for operating system and/or user files.\nRAM:: Temporarily stores information the CPU uses during operation.\nKeyboard:: Used to enter text or control items on the screen.\nMouse:: Used to point to and select items on your computer screen.\nMonitor:: Displays information in visual form using text and graphics.\n====\n\nIf you want the description and content to appear on the same line, add the horizontal style to the list.\n\n[source]\n----\n[horizontal]\nCPU:: The brain of the computer.\nHard drive:: Permanent storage for operating system and/or user files.\nRAM:: Temporarily stores information the CPU uses during operation.\n----\n\n====\n[horizontal]\nCPU:: The brain of the computer.\nHard drive:: Permanent storage for operating system and/or user files.\nRAM:: Temporarily stores information the CPU uses during operation.\n====\n\nThe content of a description list can be any AsciiDoc element.\nFor instance, we could rewrite the grocery list from above so that each aisle is a description rather than a parent outline list item.\n\n[source]\n----\nDairy::\n* Milk\n* Eggs\nBakery::\n* Bread\nProduce::\n* Bananas\n----\n\n====\nDairy::\n* Milk\n* Eggs\nBakery::\n* Bread\nProduce::\n* Bananas\n====\n\nDescription lists are quite lenient about whitespace, so you can spread the items out and even indent the content if that makes it more readable for you:\n\n[source]\n----\nDairy::\n\n\t* Milk\n\t* Eggs\n\nBakery::\n\n\t* Bread\n\nProduce::\n\n\t* Bananas\n----\n\n==== Hybrid lists\n\n[#three-hybrid]\nFinally, you can mix and match the three list types within a single hybrid list.\nAsciidoctor works hard to infer the relationships between the items that are most intuitive to us humans.\n\nHere's a list that mixes description, ordered, and unordered list items:\n\n[source]\n----\nOperating Systems::\n\tLinux:::\n\t\t. Fedora\n\t\t\t* Desktop\n\t\t. Ubuntu\n\t\t\t* Desktop\n\t\t\t* Server\n\tBSD:::\n\t\t. FreeBSD\n\t\t. NetBSD\n\nCloud Providers::\n\tPaaS:::\n\t\t. OpenShift\n\t\t. CloudBees\n\tIaaS:::\n\t\t. Amazon EC2\n\t\t. Rackspace\n----\n\nHere's how the list is rendered:\n\n.A hybrid list\n====\nOperating Systems::\n\tLinux:::\n\t\t. Fedora\n\t\t\t* Desktop\n\t\t. Ubuntu\n\t\t\t* Desktop\n\t\t\t* Server\n\tBSD:::\n\t\t. FreeBSD\n\t\t. NetBSD\n\nCloud Providers::\n\tPaaS:::\n\t\t. OpenShift\n\t\t. CloudBees\n\tIaaS:::\n\t\t. Amazon EC2\n\t\t. Rackspace\n====\n\nYou can include more complex content in a list item as well.\n\n=== Links and images\n\nAsciiDoc makes it easy to include links, images and other types of media in a document.\n\n==== External links\n\nThere's nothing you have to do to make a link to a URL.\nJust include the URL in the document and AsciiDoc will turn it into a link.\n\nAsciidoctor recognizes the following common schemes without the help of any markup.\n\n[#schemes]\n* http\n* https\n* ftp\n* irc\n* mailto\n* email@email.com\n\nYou can think of these like implicit macro names (the bare email address being a special case).\nSince the URL in the example below begins with a protocol (in this case _https_ followed by a colon), Asciidoctor will automatically turn it into a hyperlink when it is processed.\n\n[source]\n----\nThe homepage for the Asciidoctor Project is https://asciidoctor.org. <1>\n----\n<1> The trailing period will not get caught up in the link.\n\nTo prevent automatic linking of an URL, prepend it with a backslash (\\).\n\n[source]\n----\nOnce launched, the site will be available at https://example.org.\n----\n\nIf you prefer URLs to be shown with the scheme hidden, set the hide-uri-scheme attribute in the document's header.\n\n[source]\n----\n:hide-uri-scheme:\n\nhttps://asciidoctor.org\n----\n\nWhen the hide-uri-scheme attribute is set, the above URL will render as follows:\n\n[source,xml]\n----\n<a href=\"https://asciidoctor.org\">asciidoctor.org</a>\n----\n\nNote the absence of _https_ inside the <a> element.\n\nTo attach a URL to text, enclose the text in square brackets at the end of the URL, thus making it an URL macro:\n\n[source]\n----\nChat with other Fedora users in the irc://irc.freenode.org/#fedora[Fedora IRC channel].\n----\n\nWhen a URL does not start with one of the <<schemes,common schemes>>, or the URL is not surrounded by word boundaries, you must use the link macro.\nThe link macro is a stronger version of a URI macro, which you can think of like an unconstrained macro.\nThe URL is preceded by link: and followed by square brackets.\nThe square brackets may include optional link text.\nThe URL is used for the text of the link if link text is not specified.\nPrior to 1.5.7, if the linkattrs document attribute is set, the text in square brackets is parsed as attributes, which allows a window name or role to be specified.\nSince 1.5.7, attributes are parsed automatically if an equal sign is found after a comma (e.g., [link text,window=_blank]).\n\n.Anatomy of a link macro\n[source]\n----\nlink:url[optional link text, optional target attribute, optional role attribute]\n----\n\nLet's consider a case where we need to use the link macro (instead of just a URI macro) to expand a link when it's not adjacent to a word boundary (i.e., unconstrained).\n\n[source]\n----\nsearch/link:https://ecosia.org[Ecosia]\n----\n\n====\nsearch/link:https://ecosia.org[Ecosia]\n====\n\nIf we didn't use the link: prefix in this case, the URL macro would not be detected by the parser.\n\n==== Target window and role attributes for links\n\n[#link-macro-attributes]\nPrior to 1.5.7, Asciidoctor _does not_ parse attributes in the link macro by default.\nIf you want attributes in the link macro to be parsed, you must set the linkattrs document attribute in the header.\nSince 1.5.7, this parsing is automatic (and the attribute is not required) if an equal sign is found after a comma.\nWhen attribute parsing is enabled, you can then specify the name of the target window using the window attribute.\n\n[source]\n----\n= Asciidoctor Document Title\n\nLet's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage,window=_blank].\n----\n\n====\nLet's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage,window=_blank].\n====\n\nSince _blank is the most common window name, we've introduced shorthand for it.\nJust end the link text with a caret (+^+):\n\n[source]\n----\nLet's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^].\n----\n\nCAUTION: If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash.\n\nWhen attribute parsing is enabled, you can add a role (i.e., CSS class) to the link.\n\n[source]\n----\nChat with other Asciidoctor users on the https://discuss.asciidoctor.org/[*mailing list*^,role=green].\n----\n\n====\nChat with other Asciidoctor users on the https://discuss.asciidoctor.org/[*mailing list*^,role=green].\n====\n\nTIP: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor.\nWhen they're enabled, you must surround the link text in double quotes if it contains a comma.\n\n==== Links to relative files\n\nIf you want to link to an external file relative to the current document, use the link macro in front of the file name.\n\n[source]\n----\nlink:protocol.json[Open the JSON file]\n----\n\nIf your file is an HTML file, you can link directly to a section in the document, append a hash (#) followed by the section's ID to the end of the file name.\n\n[source]\n----\nlink:external.html#livereload[LiveReload]\n----\n\nFor links to relative AsciiDoc documents cross references should be used.\n\n[reftext=\"Internal Cross References\"]\n==== Cross references\n\nA link to another location within an AsciiDoc document or between AsciiDoc documents is called a _cross reference_ (also referred to as an _xref_).\n\nIn Asciidoctor, the inline xref macro is used to create cross references (also called in-text or page citations) to content elements (sections, blocks, or phrases) that have an ID (regardless of whether that ID is explicit or auto-generated).\n\nYou create a cross reference by enclosing the ID of the target block or section (or the path of another document with an optional anchor) in double angled brackets.\n\n.Cross reference using the ID of the target section\n[source]\n----\nThe section <<images>> describes how to insert images into your document.\n----\n\n.Rendered cross reference using the ID of the target section\n====\nThe section <<images>> describes how to insert images into your document.\n====\n\nYou can also link to a block or section using the title by referencing its title, referred to as a [.term]_natural cross reference_.\nThe title must contain at least one space character or contain at least one uppercase letter.\n(If you are using Ruby < 2.4, that uppercase letter is restricted to the basic Latin charset).\n\n.Cross reference using a section's title\n[source]\n----\nRefer to <<Internal Cross References>>.\n----\n\n.Rendered cross reference using a section's title\n====\nRefer to <<Internal Cross References>>.\n====\n\nConverters usually use the reftext of the target as the default text of the link.\nWhen the document is parsed, attribute references in the reftext are substituted immediately.\nWhen the reftext is displayed, additional reftext substitutions are applied to the text (specialchars, quotes, and replacements).\n\nYou can override the reftext of the target by specifying alternative text at the location of the cross reference.\nAfter the ID, add a comma and then enter the custom text you want the cross reference to display.\n\n.Cross reference with custom xreflabel text\n[source]\n----\nLearn how to <<link-macro-attributes,use attributes within the link macro>>.\n----\n\n.Rendered cross reference using custom xreflabel text\n====\nLearn how to <<link-macro-attributes,use attributes within the link macro>>.\n====\n\nYou can also use the inline xref macro as an alternative to the double angled bracket form.\n\n.Inline xref macro\n[source]\n----\nLearn how to xref:link-macro-attributes[use attributes within the link macro].\n----\n\nCross references can also be used to create a link to a file relative to the current document.\nFor links to another AsciiDoc document, this is the preferred way.\n\nThe trailing hash (#) means that you refer to the top of the document.\n\n.Cross reference to the top of a relative AsciiDoc document\n[source]\n----\nRefer to <<document-b.adoc#,Document B>> for more information.\n----\n\n.Converted HTML for cross reference to relative AsciiDoc document\n[source,html]\n----\nRefer to <a href=\"document-b.html\">Document B</a> for more information.\n----\n\nTo link directly to a section in the document, append the section's ID after the hash (#).\n\n.Cross reference to a specific section of a relative AsciiDoc document\n[source]\n----\nRefer to <<document-b.adoc#section-b,Section B>> for more information.\n----\n\n.Converted HTML for cross reference to section of a relative AsciiDoc document\n[source,html]\n----\nRefer to <a href=\"document-b.html#section-b\">Section B</a> for more information.\n----\n\nIn both cases, this syntax will also work if you are inside the document you are referring to.\nThis is useful if you are sharing the same link across multiple documents.\n\nIn the link that is created from the inter-document cross reference, the source file extension is replaced with the value of the outfilesuffix attribute.\nTo customize the file extension used in the target of the link, simply change the value of this attribute.\n\nImage references are similar to links since they are also references to URLs or files.\nThe difference, of course, is that they display the image in the document.\n\n==== Images\n\nTo include an image on its own line (i.e., a _block image_), use the image:: prefix in front of the file name and square brackets after it:\n\n[source]\nimage::sunset.jpg[]\n\nIf you want to specify alt text, include it inside the square brackets:\n\n[source]\nimage::sunset.jpg[Sunset]\n\nYou can also give the image an id, a title (i.e., caption), set its dimensions (i.e., width and height) and make it a link:\n\n[source]\n----\n[#img-sunset]\n.A mountain sunset\n[link=https://www.flickr.com/photos/javh/5448336655]\nimage::sunset.jpg[Sunset,300,200]\n----\n\nThe title of a block image is displayed underneath the image when rendered.\nHere's a preview:\n\n.A hyperlinked image with caption\n====\n[#img-sunset]\n.A mountain sunset\n[link=https://www.flickr.com/photos/javh/5448336655]\nimage::sunset.jpg[Sunset,300,200]\n====\n\nIMPORTANT: Images are resolved relative to the value of the imagesdir document attribute, which defaults to an empty value.\nThe imagesdir attribute can be an absolute path, relative path or base URL.\nIf the image target is a URL or an absolute path, the imagesdir prefix is _not_ added.\n\nTIP: You should use the imagesdir attribute to avoid hard coding the shared path to your images in every image macro.\n\nIf you want to include an image inline, use the image: prefix instead (notice there is only one colon):\n\n[source]\nPress the image:save.png[Save, title=\"Save\"] button.\n\nFor inline images, the optional title is displayed as a tooltip.\n\nIf paragraphs and lists are the meat of the document, then titles and sections are its bones.\nLet's explore how to give structure to our document.\n\n=== Titles, titles, titles\n\nAsciiDoc supports three types of titles:\n\n. Document title\n. Section title\n. Block title\n\nAll titles are optional in AsciiDoc.\nThis section will define each title type and explain how and when to use them.\n\n==== Document title\n\nJust as every e-mail has a subject, every document (typically) has a title.\nThe title goes at the top of an AsciiDoc document.\n\nTIP: A document title is an _optional_ feature of an AsciiDoc document.\n\nTo create a document title, begin the first line of the document with one equal sign followed by at least one space (\\= \\), then the text of the title.\nThis syntax is the simplest (and thus recommended) way to declare a document title.\n\nHere's an example of a document title followed by an abbreviated paragraph:\n\n[source]\n----\n= Lightweight Markup Languages\n\nAccording to Wikipedia...\n----\n\nThe document title is part of the document header.\nSo, what else can go in the header?\nGood question.\n\n===== The document header\n\nNotice the blank line between the title line and the first line of content in the previous example.\nThis blank line separates the document header from the document body (in this case a paragraph).\nThe document title is part of the document header.\nIn all, the document header contains the title, author, revision information and document-wide attributes.\n\nCAUTION: If the title line is not offset by a blank line, it gets interpreted as a section title, which we'll discuss later.\n\nYour document now has a title, but what about an author?\nJust as every e-mail has a sender, every document must surely have an author.\nLet's see how to add additional information to the header, including an author.\n\nThere are two optional lines of text you can add immediately below the document title for defining common document attributes:\n\nLine 1:: Author name and an optional e-mail address\nLine 2:: An optional revision, a date and an optional remark\n\nLet's add these lines to our document:\n\n[source]\n----\n= Lightweight Markup Languages\nDoc Writer <doc.writer@asciidoc.org>\nv1.0, 2012-01-01\n\nAccording to Wikipedia...\n----\n\nThe header now contains a document title, an author, a revision number, and a date.\nThis information will typically be displayed as a formatted header at the top of the output document.\n\nNOTE: The header, including the document title, is _not required_.\nIf absent, the AsciiDoc processor will happily convert whatever content is present.\nThe header is only used when generating a full document.\nIt's excluded from the output of an embedded document.\n\nThe document header can also be used to define attributes.\n\n==== Document attributes\n\nAttributes are one of the features that sets AsciiDoc apart from other lightweight markup languages.\nYou can use attributes to toggle features or to store reusable or replacement content.\n\nMost often, attributes are defined in the document header.\nThere are scenarios where they can be defined inline, but we'll focus on the more common usage.\n\nAn attribute entry consists of a name surrounded by colons at the beginning of the line followed by at least one space, then the content.\nThe content is optional.\n\nHere's an example of an attribute that holds the version of an application:\n\n[source]\n----\n= User Guide\nDoc Writer <doc.writer@asciidoc.org>\n2012-01-01\n:appversion: 1.0.0\n----\n\nIMPORTANT: There should be no blank lines between the first attribute entry and the rest of the header.\n\nNow you can refer to this attribute anywhere in the document (where attribute substitution is performed) by surrounding the name in curly braces:\n\n[source]\nThe current version of the application is {appversion}.\n\nAttributes are also commonly used to store URLs, which can get quite lengthy.\nHere's an example:\n\n[source]\n----\n:fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor\n----\n\nHere's the attribute in use:\n\n[source]\nInformation about the Asciidoctor package for Fedora can found at {fedpkg}.\n\nDocument attributes can also be used to toggle settings or set configuration variables that control the output generated by the AsciiDoc processor.\n\nFor example, to include a table of contents in your document, you can define the \toc attribute:\n\n[source]\n----\n:toc:\n----\n\nTo undefine an attribute, place a ! at the end of the name:\n\n[source]\n----\n:linkcss!:\n----\n\nYou can also set the base path to images (default: _empty_), icons (default: ./images/icons), stylesheets (default: ./stylesheets) and JavaScript files (default: ./javascripts):\n\n[source]\n----\n:imagesdir: ./images\n:iconsdir: ./icons\n:stylesdir: ./styles\n:scriptsdir: ./js\n----\n\nTIP: Attribute values can also be set and overridden when invoking the AsciiDoc processor.\nWe'll explore that feature later.\n\nWhen you find yourself typing the same text repeatedly, or text that often needs to be updated, consider assigning it to a document attribute and use that instead.\n\nAs your document grows, you'll want to break the content into sections, like in this guide.\nThat's accomplished using section titles.\n\n==== Section titles\n\nSections partition the document into a content hierarchy.\nIn AsciiDoc, sections are defined using section titles.\n\nA section title uses the same syntax as a document title, except the line may begin with two to six equal signs instead of just a single equal sign.\nThe number of equal signs represents the nesting level (using a 0-based index).\n\nHere are all the section levels permitted in an AsciiDoc document (for an article doctype, the default), shown below the document title:\n\n[source]\n----\n= Document Title (Level 0)\n\n== Level 1 Section\n\n=== Level 2 Section\n\n==== Level 3 Section\n\n===== Level 4 Section\n\n====== Level 5 Section\n\n== Another Level 1 Section\n----\n\nNOTE: When the document is converted to HTML 5 (using the built-in html5 backend), each section title becomes a heading element where the heading level matches the number of equal signs.\nFor example, a level 1 section (2 equal signs) maps to an <h2> element.\n\nSection levels cannot be chosen arbitrarily.\nThere are two rules you must follow:\n\n. A document can only have multiple level 0 sections if the doctype is set to \book.footnote:[The default doctype is article, which only allows one level 0 section (i.e., the document title).]\n. Section levels cannot be skipped when nesting sections\n\nFor example, the following syntax is illegal:\n\n[source]\n----\n= Document Title\n\n= Illegal Level 0 Section (violates rule #1)\n\n== First Section\n\n==== Illegal Nested Section (violates rule #2)\n----\n\nContent above the first section (after the document title) is part of the preamble.\nOnce the first section is reached, content is associated with the section that precedes it:\n\n[source]\n----\n== First Section\n\nContent of first section\n\n=== Nested Section\n\nContent of nested section\n\n== Second Section\n\nContent of second section\n----\n\nTIP: In addition to the equals marker used for defining single-line section titles, Asciidoctor recognizes the hash symbol (#) from Markdown.\nThat means the outline of a Markdown document will convert just fine as an AsciiDoc document.\n\nTo have the processor auto-number the sections, define the sectnums attribute in the document header:\n\n[source]\n----\n:sectnums:\n----\n\nYou can also use this attribute entry above any section title in the document to toggle the auto-numbering setting.\nWhen you want to turn off the numbering, add an exclamation point to the end of the attribute name:\n\n[source]\n----\n:sectnums!:\n\n== Unnumbered Section\n----\n\n===== Preamble\n\nContent between the document title and the first section is called the preamble.\nIf a document title is not present, this content is not wrapped in a preamble section.\n\n[source]\n----\n= Document Title\n\npreamble\n\nanother preamble paragraph\n\n== First Section\n----\n\nTIP: When using the default Asciidoctor stylesheet, this preamble is rendered in the style of a lead (i.e., larger font).\n\nYou can also assign titles to individual elements.\n\n==== Block titles\n\nYou can assign a title to any paragraph, list or delimited block element.\nThe title is used as the element's caption.\nIn most cases, the title is displayed immediately above the content.\nIf the content is a figure or image, the title is displayed below the content.\n\nA block title is defined on a line above the element.\nThe line must begin with a dot (.) and be followed immediately by the title text with no spaces in between.\n\nHere's an example of a list with a title:\n\n[source]\n----\n.TODO list\n- Learn the AsciiDoc syntax\n- Install AsciiDoc\n- Write my document in AsciiDoc\n----\n\nSpeaking of block titles, let's dig into blocks and discover which types of blocks AsciiDoc supports.\n\n== Building blocks in AsciiDoc\n\nAsciiDoc provides a nice set of components for including non-paragraph text--such as block quotes, source code listings, sidebars and tables--in your document.\nThese components are referred to as _delimited blocks_ because they are surrounded by delimiter lines.\n\n=== Delimited blocks\n\nYou've already seen many examples of the listing block (i.e., code block), which is surrounded by lines with four or more hyphens.\n\n[source]\n....\n----\nThis is an example of a _listing block_.\nThe content inside is displayed as <pre> text.\n----\n....\n\nWithin the boundaries of a delimited block, you can enter any content or blank lines.\nThe block doesn't end until the ending delimiter is found.\nThe delimiters around the block determine the type of block, how the content is processed and converted and what elements are used to wrap the content in the output.\n\nHere's how the block above appears when converted to HTML and viewed in a browser:\n\n....\nThis is an example of a _listing block_.\nThe content inside is displayed as <pre> text.\n....\n\nHere's the HTML source that is generated:\n\n[source,html]\n----\n<div class=\"listingblock\">\n\t<div class=\"content monospaced\">\n\t\t<pre>This is an example of a _listing block_.\nThe content inside is displayed as &lt;pre&gt; text.</pre>\n\t</div>\n</div>\n----\n\nYou should notice a few things about how the content is processed:\n\n* the HTML tag <pre> is escaped\n* the endlines are preserved\n* the phrase \"listing block\" is not italicized, despite having underscores around it.\n\nEach type of block is processed according to its purpose.\nLiteral blocks don't receive the full set of substitutions normally applied to a paragraph.\nSince a listing block is typically used for source code, substitutions are not desirable.\n\nThe following table identifies the delimited blocks that AsciiDoc provides by default, their purpose and what substitutions are performed on its content.\n\n[cols=\"1,1l,1,1\"]\n|===\n|Name (Style) |Line delimiter |Purpose |Substitutions\n\n|comment\n|////\n|Private notes that are not displayed in the output\n|none\n\n|example\n|====\n|Designates example content or defines an admonition block\n|normal\n\n|literal\n|....\n|Output text to be displayed exactly as entered\n|verbatim\n\n|listing, source\n|----\n|Source code or keyboard input to be displayed as entered\n|verbatim\n\n|open\n|--\n|Anonymous block that can act as any other block (except _pass_ or _table_)\n|varies\n\n|pass\n|++++\n|Raw text to be passed through unprocessed\n|none\n\n|quote, verse\n|____\n|A quotation or verse with optional attribution\n|normal\n\n|sidebar\n|****\n|Aside text displayed outside the flow of the document\n|normal\n\n|table\n||===\n|Used to display tabular content or advanced layouts\n|varies\n|===\n\nIMPORTANT: AsciiDoc allows delimited lines to be longer than 4 characters.\n*Don't do it.*\nMaintaining long delimiter lines is a _colossal_ waste of time, not to mention arbitrary and error prone.\nUse the minimum line length required to create a delimited block and _move on_ to drafting the content.\nThe reader will never see the long delimiters anyway since they are not carried over to the output.\n\nThis table shows the substitutions performed by each substitution group referenced in the previous table.\n\n|===\n|Group / Substitution |Normal |Verbatim |None\n\nh|Special chars\n|Yes\n|Yes\n|No\n\nh|Callouts\n|No\n|Yes\n|No\n\nh|Quotes\n|Yes\n|No\n|No\n\nh|Attributes\n|Yes\n|No\n|No\n\nh|Replacements\n|Yes\n|No\n|No\n\nh|Macros\n|Yes\n|No\n|No\n\nh|Post replacements\n|Yes\n|No\n|No\n|===\n\nIn order to apply normal substitutions to an attribute value, surround it with single quotes.\nThere are two exceptions to this behavior: At the moment normal substitutions are not applied to\nthe options and \title attribute values.\n\nYou can control how blocks are displayed using block metadata.\n\n=== Block metadata\n\nMetadata can be assigned to any block.\nThere are several types of metadata:\n\n* Title\n* Id (i.e., anchor)\n* Style (first unnamed block attribute)\n* Named block attributes\n\nHere's an example of a quote block that includes all types of metadata:\n\n[source]\n----\n.Gettysburg Address\n[[gettysburg]]\n[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]\n____\nFour score and seven years ago our fathers brought forth\non this continent a new nation...\n\nNow we are engaged in a great civil war, testing whether\nthat nation, or any nation so conceived and so dedicated,\ncan long endure. ...\n____\n----\n\nHere's the metadata extracted from this block:\n\nTitle:: Gettysburg Address\nId:: gettysburg\nStyle:: quote\nNamed block attributes::\n\tattribution::: Abraham Lincoln\n\tcitetitle::: Address delivered at the dedication of the Cemetery at Gettysburg\n\nTIP: A block can have multiple block attribute lines.\nThe attributes will be aggregated.\nIf there is a name conflict, the last attribute defined wins.\n\nSome metadata is used as supplementary content, such as the title, whereas other metadata, such as the style, controls how the block is converted.\n\n=== Masquerading blocks\n\nSome blocks can masquerade as other blocks, a feature which is controlled by the block style.\nThe block style is the first positional attribute in the block attribute list.\n\n==== Admonition blocks\n\nFor instance, an example block can act as an admonition block:\n\n[source]\n----\n[NOTE]\n====\nThis is an example of an admonition block.\n\nUnlike an admonition paragraph, it may contain any AsciiDoc content.\nThe style can be any one of the admonition labels:\n\n* NOTE\n* TIP\n* WARNING\n* CAUTION\n* IMPORTANT\n====\n----\n\n==== Listing and source code blocks\n\nAt the start of this tutorial, remember how painful we said it is to insert source code into a document using a traditional word processor.\nThey just aren't designed for that use case.\n*AsciiDoc is!*\n\nIn fact, inserting source code in an AsciiDoc is incredibly easy.\nJust shove the raw code into a listing block.\n\n[source]\n....\n----\nrequire 'asciidoctor'\n\nputs Asciidoctor.convert_file 'mysample.adoc', to_file: false\n----\n....\n\nTo enable syntax highlighting in the output, set the style on the block to \\source\\ and specify the source language in the second attribute position.\n\n[source]\n....\n[source,ruby]\n----\nrequire 'asciidoctor'\n\nputs Asciidoctor.convert_file 'mysample.adoc', to_file: false\n----\n....\n\nYou can even use source code that's in a separate file.\nJust use the AsciiDoc include directive:\n\n[source]\n....\n[source,ruby]\n----\ninclude::example.rb[]\n----\n....\n\nTo really show how well-suited AsciiDoc is for technical documentation, it also supports callouts in source code.\nCode callouts are used to explain lines of source code.\nThe explanations are specified below the listing and keyed by number.\nHere's an example:\n\n[source]\n....\n[source,ruby]\n----\nrequire 'asciidoctor'  # <1>\n\nAsciidoctor.convert_file 'mysample.adoc'  # <2>\n----\n<1> Imports the library\n<2> Reads, parses, and converts the file\n....\n\nHere's how the callouts appear when rendered:\n\n[#eg-callouts]\n.Source code with callouts\n====\n[source,ruby]\n----\nrequire 'asciidoctor'  # <1>\n\nputs Asciidoctor.convert_file 'mysample.adoc'  # <2>\n----\n<1> Imports the library\n<2> Reads, parses, and converts the file\n====\n\n==== Open blocks\n\nThe most versatile block of all is the open block.\nAn open block can act as any other block, with the exception of _pass_ and _table_.\nHere's an example of an open block acting as a sidebar:\n\n[source]\n----\n[sidebar]\n.Related information\n--\nThis is aside text.\n\nIt is used to present information related to the main content.\n--\n----\n\n[#pass-blocks]\n==== Passthrough blocks\n\nThe \"anything goes\" mechanism in AsciiDoc is the passthrough block.\nAs the name implies, this block passes the content of the block directly through to the output document.\nWhen you've encountered a complex requirement that you cannot meet using the AsciiDoc syntax, a passthrough block can come in very handy.\n\nFor example, let's say you want to embed a GitHub gist into your document.\nYou can define the following passthrough block:\n\n[source]\n----\n++++\n<script src=\"https://gist.github.com/piscisaureus/3342247.js\"></script>\n++++\n----\n\n////\n[source]\n----\n++++\n<video poster=\"images/movie-reel.png\">\n\t<source src=\"videos/writing-zen.webm\" type=\"video/webm\">\n</video>\n++++\n----\n////\n\nCAUTION: Using a passthrough block couples your content to a specific output format, such as HTML.\nIf you're going to use a passthrough block, we recommend using {user-ref}#conditional-preprocessor-directives[conditional preprocessor directives] to associate the format-specific content with each backend you intend to support.\n\n//The block style can be used in the absense of block delimiters to promote a paragraph to a block element.\n\n=== Delimiters optional\n\nIf the content is contiguous (not interrupted by blank lines), you can forgo the use of the block delimiters and instead use the block style above a paragraph to repurpose it as one of the delimited block types.\n\nThis format is often used for single-line listings:\n\n[source]\n----\n[listing]\nsudo dnf install asciidoc\n----\n\nor single-line quotes:\n\n[source]\n----\n[quote]\nNever do today what you can put off 'til tomorrow.\n----\n\nWhile most blocks are linear, tables give you the ability to layout content horizontally as well.\n\n=== A new perspective on tables\n\nTables are one of the most refined areas of the AsciiDoc syntax.\nThey are easy to create, easy to read in raw form and also remarkably sophisticated.\nI recommend that you use tables sparingly because they interrupt the conversation with your readers.\nWhen they are the most suitable way to present the information, know that you've got a powerful tool in your hands.\n\nYou can think of a table as a delimited block that contains one or more bulleted lists.\nThe list marker is a vertical bar (|).\nEach list represents one row in the table and must share the same number of items (taking into account any column or row spans).\n\nHere's a simple example of a table with two columns and three rows:\n\n[source]\n----\n[cols=2*]\n|===\n|Firefox\n|Web Browser\n\n|Ruby\n|Programming Language\n\n|TorqueBox\n|Application Server\n|===\n----\n\nThe first non-blank line inside the block delimiter (|===) determines the number of columns.\nSince we are putting each column title on a separate line, we have to use the cols block attribute to explicitly state that this table has two columns.\nThe * is the repeat operator.\nIt means to repeat the column specification for the remainder of columns.\nIn this case, it means to repeat no special formatting (since none is present) across 2 columns.\n\nWe can make the first row of the table the header by setting the header option on the table.\n\n[source]\n----\n[cols=2*,options=header]\n|===\n|Name\n|Group\n\n|Firefox\n|Web Browser\n\n|Ruby\n|Programming Language\n\n...\n|===\n----\n\nYou can also define the header option using the following shorthand:\n\n\\[%header,cols=2*]\n\\\nAlternatively, we could define the header row on a single line offset from the body rows by a blank line, so neither the cols nor the options attributes are required.\n\n[source]\n----\n|===\n|Name |Group\n\n|Firefox\n|Web Browser\n\n...\n|===\n----\n\nThe content of each item (i.e., cell) can span multiple lines, as is the case with other lists in AsciiDoc.\nUnlike other lists, the content of each cell may contain blank lines without the need for a list continuation to hold them together.\nA new cell begins when another non-escaped vertical bar (|) is encountered.\n\n[source]\n----\n|===\n|Name |Group |Description\n\n|Firefox\n|Web Browser\n|Mozilla Firefox is an open-source web browser.\nIt's designed for standards compliance,\nperformance, portability.\n\n|Ruby\n|Programming Language\n|A programmer's best friend.\n\n...\n|===\n----\n\nYou can set the relative widths of each column using _column specifiers_{mdash}a comma-separated list of relative values defined in the cols block attribute.\nThe number of entries in the list determines the number of columns.\n\n[source]\n----\n[cols=\"2,3,5\"]\n|===\n|Name |Group |Description\n\n|Firefox\n|Web Browser\n|Mozilla Firefox is an open-source web browser.\nIt's designed for standards compliance,\nperformance and portability.\n\n|Ruby\n|Programming Language\n|A programmer's best friend.\n\n...\n|===\n----\n\nIf you want to include blocks or lists inside the contents of a column, you can put an a (for AsciiDoc) at the end of the column's relative value.\n\n[source]\n----\n[cols=\"2,3,5a\"]\n|===\n|Name |Group |Description\n\n|Firefox\n|Web Browser\n|Mozilla Firefox is an open-source web browser.\nIt's designed for:\n\n* standards compliance,\n* performance and\n* portability.\n\n|Ruby\n|Programming Language\n|A programmer's best friend.\n\n...\n|===\n----\n\nAlternatively, you can apply the AsciiDoc style to an individual cell by prefixing the vertical bar with an a:\n\n[source]\n----\na|Mozilla Firefox is an open-source web browser.\nIt's designed for:\n\n* standards compliance,\n* performance and\n* portability.\n----\n\nThere's a whole collection of column and cell specifiers you can use to format the contents of the table, including styling and alignment.\n\nAsciiDoc tables can also be created directly from CSV data.\nJust set the \format block attribute to csv and insert CSV data inside the block delimiters, either directly:\n\n[source]\n----\n[%header,format=csv]\n|===\nArtist,Track,Genre\nBaauer,Harlem Shake,Hip Hop\nThe Lumineers,Ho Hey,Folk Rock\n|===\n----\n\nor using an include::[] directive:\n\n[source]\n----\n[%header,format=csv]\n|===\ninclude::tracks.csv[]\n|===\n----\n\nAsciidoctor 0.1.3 also recognizes shorthand notation for setting CSV and DSV table formats.\nThe first position of the table block delimiter (i.e., |===) can be replaced by a data delimiter to set the table format accordingly.\n\nInstead of specifying the csv format using an attribute, you can simply replace the leading pipe (|) with a comma (,).\n\n//[source]\n----\n,===\na,b,c\n,===\n----\n\nIn the same way, the dsv format can be specified by replacing the leading pipe (|) with a colon (:).\n\n//[source]\n----\n:===\na:b:c\n:===\n----\n\nThat's a pretty powerful option.\n\n== What else can AsciiDoc do?\n\nWe've covered many of the features of the AsciiDoc syntax, but it still has much more depth.\nAsciiDoc is simple enough for a README, yet can scale to meet the requirements of a publisher.\n\nHere are some of the features that the AsciiDoc syntax supports:\n\n* footnotes\n* indexes\n* appendix, preface, dedication, partintro\n* multi-line attributes\n* preprocessor directive (conditional markup)\n* mathematical formulas\n* musical notation\n* diagrams\n* block filters\n* themes\n* custom blocks, macros and output formats\n\nConsult the {user-ref}[Asciidoctor User Manual] to continue exploring the syntax and processor capabilities.\n\nThat's enough syntax for now.\nYou've created your first AsciiDoc document.\nNow it's time to convert the document into a presentable format.\nThis will give you a real appreciation for the power that AsciiDoc puts in your hands.\n\n== Converting your document\n\nWhile AsciiDoc syntax is designed to be readable in raw form, the intended audience for that format are writers and editors.\nReaders aren't going to appreciate the raw text nearly as much.\nAesthetics matter.\nYou'll want to apply nice typography with font sizes that adhere to the \"golden ratio\", colors, icons and images to give it the respect it deserves.\nThat's where the Asciidoctor processor comes in (*after* you have done the writing).\n\nThe Asciidoctor processor parses the document and translates it into a backend format, such as HTML, ePub, DocBook or PDF.\nAsciidoctor ships with a set of default templates in the tin, but you can customize the templates or create your own to get exactly the output you want.\n\nBefore you can use the Asciidoctor processor, you have to install the {asciidoctor-gem-ref}[Asciidoctor Ruby Gem].\nReview the {uri-install}[Asciidoctor Installation Guide] if you need help to install the gem.\n\n=== Converting a document to HTML 5\n\nAsciidoctor provides both a command line tool and a Ruby API for converting AsciiDoc documents to HTML 5, Docbook 5.0 and custom output formats.\n\nTo use Asciidoctor to generate an HTML document, type asciidoctor followed by your document's name on the command line.\n\n $ asciidoctor mysample.adoc\n\nIn Asciidoctor, the *html5* backend is the default, so there's no need to specify a backend explicitly to generate an HTML 5 document.\n\nAsciidoctor also provides a Ruby API, so you can generate an HTML document directly from a Ruby application:\n\n[source,ruby]\n----\nrequire 'asciidoctor'\n\nAsciidoctor.convert_file 'mysample.adoc'\n----\n\nAlternatively, you can capture the HTML output into a variable instead of writing it to a file:\n\n[source,ruby]\n----\nhtml = Asciidoctor.convert_file 'mysample.adoc', to_file: false, header_footer: true\nputs html\n----\n\nTo generate DocBook, just specify the backend option:\n\n[source,ruby]\n----\nAsciidoctor.convert_file 'mysample.adoc', backend: 'docbook'\n----\n\nOne of the strengths of Asciidoctor is that it can output to a variety of formats, not just HTML.\n\n=== Converting a document to DocBook\n\nDespite the fact that writing in DocBook is inhumane, it's useful as a portable document format.\nSince AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good.\nThere's a corresponding DocBook element for each markup in the AsciiDoc syntax.\n\nAsciidoctor provides a Docbook 5.0 backend out of the box.\nTo convert the document to Docbook 5.0, call the processor with the backend flag set to docbook5:\n\n $ asciidoctor -b docbook5 mysample.adoc\n\nA new XML document, named mysample.xml, will now be present in the current directory:\n\n $ ls -1\n mysample.adoc\n mysample.html\n mysample.xml\n\nIf you're on Linux, you can view the DocBook file using Yelp:\n\n $ yelp mysample.xml\n\nDocBook is only an intermediary format in the Asciidoctor toolchain.\nYou'll either feed it into a system that processes DocBook (like {publican-ref}[publican]), or you can convert it to PDF using the {fopub-doc-ref}[asciidoctor-fopub tool].\n\n=== Output galore\n\nThere's really no end to the customization you can do to the output the Asciidoctor processor generates.\nWe've just scratched the surface here.\n\nCheck out the {user-ref}[Asciidoctor User Manual] and the {docs-ref}[Asciidoctor Docs Page] to learn more.\n\n=== Where else is AsciiDoc supported?\n\nThe easiest way to experiment with AsciiDoc is online.\nAsciiDoc document in a GitHub repository/link:{gist-ref}[gist] or Codeberg repository is automatically converted to HTML and rendered in the web interface.\nGitLab respositories/link:{snippets-ref}[snippets] are supported as well—including the include::[] directive.\n\nIf you have a project on GitHub, or GitLab, or Codeberg, you can write the README or any other documentation in AsciiDoc and the Git forge's interface will show the HTML output for visitors to view.\n\n// image?\n\nGists, in particular, are a great way to experiment with AsciiDoc.\nJust create a new gist, name the file with the extension .adoc and enter AsciiDoc markup.\nYou can save the document as public or secret.\nIf you want to try AsciiDoc without installing any software, a gist is a great way to get started.\n\n// image?\n\nWhile there's plenty more of the AsciiDoc syntax and toolchain to explore, you know more than enough about it to write a range of documentation, from a simple README to a comprehensive user guide.\n\n== Wrap-up\n\nWriting in AsciiDoc should be no more complex than writing an e-mail.\nAll you need to compose a document in AsciiDoc is open a text editor and type regular paragraphs.\nOnly when you need additional semantics or formatting do you need to introduce markup.\nLet your instinct guide you when you need to remember what punctuation to use.\nThe AsciiDoc syntax is based on time-tested plain-text conventions from the last several decades of computing.\nHopefully you agree that the markup does not detract from the readability of the text in raw form, as that's a key goal of lightweight markup languages like AsciiDoc.\n\nAs humans, communication is what connects us through the ages and allows us to pass on knowledge.\nAsciiDoc enables you to focus on communicating rather than distracting you with other stuff that just gets in the way.\nCopy the text of an e-mail into a document and see how easy it to repurpose it as documentation.\nAlmost immediately, you'll find your writing zen and enjoy the rewarding experience of producing.\n\n[glossary]\n== Glossary\n\n[glossary]\nadmonition paragraph:: a callout paragraph that has a label or icon indicating its priority\nadmonition block:: a callout block containing complex content that has a label or icon indicating its priority\nbackend:: a set of templates for converting AsciiDoc source to different output format\ncross reference:: a link from one location in the document to another location marked by an anchor\nlist continuation:: a plus sign (+) on a line by itself that connects adjacent lines of text to a list item\nquoted text:: text which is enclosed in special punctuation to give it emphasis or special meaning";

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@oxide/react-asciidoc",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.20",
   "files": [
     "dist"
   ],
   "description": "React renderer for AsciiDoc",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oxidecomputer/react-asciidoc.git"
+  },
   "main": "./dist/react-asciidoc.umd.cjs",
   "module": "./dist/react-asciidoc.js",
   "exports": {
@@ -14,13 +18,11 @@
     }
   },
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/types/index.d.ts",
   "scripts": {
     "dev": "vite --port 8000",
     "clean": "rimraf dist/",
-    "build": "npm run clean && tsc && vite build",
-    "preview": "vite preview",
-    "release": "auto shipit",
+    "build": "npm run clean && vite build && tsc",
     "test:init": "rm -rf ./tests/renderer.spec.ts-snapshots & npx playwright test -g html",
     "test:run": "npx playwright test -g react",
     "fmt": "prettier --write --ignore-path ./.gitignore  .",
@@ -30,6 +32,7 @@
   "author": "Oxide Computer Company <bots@oxidecomputer.com>",
   "license": "MPL 2.0",
   "dependencies": {
+    "@asciidoctor/core": "^3.0.0-rc.2",
     "classnames": "^2.3.2",
     "highlight.js": "^11.6.0",
     "html-react-parser": "^3.0.4",
@@ -37,20 +40,20 @@
     "vitest": "^0.24.3"
   },
   "devDependencies": {
-    "@asciidoctor/core": "^3.0.0-rc.1",
     "@playwright/test": "^1.27.1",
     "@trivago/prettier-plugin-sort-imports": "^3.3.0",
     "@types/node": "^18.15.11",
     "@types/react": "^18.0.18",
     "@types/react-dom": "^18.0.6",
     "@vitejs/plugin-react": "^2.1.0",
-    "auto": "^10.37.6",
     "eslint": "^8.23.0",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.7.1",
+    "rollup-plugin-dts": "^5.3.0",
     "typescript": "^4.6.4",
     "vite": "^3.1.0",
-    "vite-plugin-dts": "^2.1.0"
+    "vite-dts": "^1.0.4",
+    "vite-plugin-dts": "^2.3.0"
   },
   "peerDependencies": {
     "react": "^18.2.0",

package/dist/index.d.ts

@@ -1,9 +0,0 @@
-import type { AbstractBlock } from '@asciidoctor/core';
-export declare const ad: import("@asciidoctor/core").Asciidoctor;
-declare const Asciidoc: ({ content }: {
-    content: string;
-}) => JSX.Element;
-export declare const Content: ({ blocks }: {
-    blocks: AbstractBlock[];
-}) => JSX.Element;
-export default Asciidoc;