From bf89b68acab26bf8683283d546a21aab838ef022 Mon Sep 17 00:00:00 2001 From: test2 Date: Thu, 17 Oct 2019 16:25:03 +0300 Subject: [PATCH] quick --- asciidoc/AsciiDocSyntaxQuickReference.adoc | 8002 +++++++++++++++++ asciidoc/_includes/about-asciidoctor.adoc | 34 + asciidoc/_includes/abstract.adoc | 76 + asciidoc/_includes/admonition.adoc | 87 + asciidoc/_includes/api-intro.adoc | 11 + asciidoc/_includes/appendix.adoc | 79 + asciidoc/_includes/apply-theme.adoc | 93 + .../_includes/asciidoc-article-template.adoc | 91 + asciidoc/_includes/asciidoctor-ant.adoc | 22 + asciidoc/_includes/attr-doc.adoc | 310 + asciidoc/_includes/attr-element.adoc | 63 + asciidoc/_includes/attr-miss.adoc | 91 + asciidoc/_includes/attr-style.adoc | 95 + asciidoc/_includes/attr-use.adoc | 54 + asciidoc/_includes/attr.adoc | 99 + asciidoc/_includes/attrs-builtin.adoc | 1035 +++ asciidoc/_includes/attrs-charref.adoc | 144 + asciidoc/_includes/attrs-env.adoc | 156 + asciidoc/_includes/author.adoc | 118 + asciidoc/_includes/benefits.adoc | 68 + asciidoc/_includes/biblio.adoc | 48 + asciidoc/_includes/block-name-table.adoc | 94 + asciidoc/_includes/block.adoc | 151 + asciidoc/_includes/book-part.adoc | 44 + asciidoc/_includes/callout-copy.adoc | 27 + asciidoc/_includes/callout-icon.adoc | 14 + asciidoc/_includes/callout-intro.adoc | 24 + asciidoc/_includes/callout-xml.adoc | 25 + asciidoc/_includes/checklist.adoc | 49 + asciidoc/_includes/cli-options.adoc | 136 + asciidoc/_includes/colophon.adoc | 13 + asciidoc/_includes/command-line-usage.adoc | 30 + asciidoc/_includes/comment.adoc | 17 + .../conditional-preprocessor-directives.adoc | 210 + .../convert-from-confluence-xhtml.adoc | 32 + asciidoc/_includes/counter.adoc | 92 + asciidoc/_includes/create-theme.adoc | 40 + asciidoc/_includes/dedication.adoc | 12 + asciidoc/_includes/discrete-heading.adoc | 33 + asciidoc/_includes/dlist-qa.adoc | 15 + asciidoc/_includes/dlist.adoc | 84 + asciidoc/_includes/docbook.adoc | 84 + asciidoc/_includes/docbookrx.adoc | 20 + asciidoc/_includes/docinfo.adoc | 246 + asciidoc/_includes/doctype.adoc | 44 + asciidoc/_includes/element.adoc | 55 + asciidoc/_includes/ex-admon.adoc | 83 + asciidoc/_includes/ex-appendix.adoc | 73 + asciidoc/_includes/ex-author.adoc | 82 + asciidoc/_includes/ex-biblio.adoc | 19 + asciidoc/_includes/ex-block.adoc | 36 + asciidoc/_includes/ex-callout.adoc | 62 + asciidoc/_includes/ex-comment.adoc | 18 + asciidoc/_includes/ex-counter.adoc | 20 + asciidoc/_includes/ex-desc.adoc | 55 + asciidoc/_includes/ex-dlist.adoc | 101 + asciidoc/_includes/ex-example.adoc | 24 + asciidoc/_includes/ex-footnote.adoc | 41 + asciidoc/_includes/ex-header-attr.adoc | 37 + asciidoc/_includes/ex-header-title.adoc | 45 + asciidoc/_includes/ex-hr.adoc | 28 + asciidoc/_includes/ex-image.adoc | 82 + asciidoc/_includes/ex-include.adoc | 96 + asciidoc/_includes/ex-keyword.adoc | 27 + asciidoc/_includes/ex-listing.adoc | 77 + asciidoc/_includes/ex-literal.adoc | 58 + asciidoc/_includes/ex-manpage.adoc | 42 + asciidoc/_includes/ex-o-list.adoc | 104 + asciidoc/_includes/ex-open.adoc | 30 + asciidoc/_includes/ex-pass.adoc | 112 + asciidoc/_includes/ex-quote.adoc | 99 + asciidoc/_includes/ex-rev.adoc | 51 + asciidoc/_includes/ex-section.adoc | 203 + asciidoc/_includes/ex-sidebar.adoc | 24 + asciidoc/_includes/ex-src.adoc | 110 + asciidoc/_includes/ex-stem.adoc | 74 + asciidoc/_includes/ex-subs.adoc | 89 + asciidoc/_includes/ex-table-cell.adoc | 157 + asciidoc/_includes/ex-table-data.adoc | 43 + asciidoc/_includes/ex-table.adoc | 362 + asciidoc/_includes/ex-text.adoc | 207 + asciidoc/_includes/ex-toc.adoc | 20 + asciidoc/_includes/ex-ui.adoc | 42 + asciidoc/_includes/ex-ulist.adoc | 205 + asciidoc/_includes/ex-url.adoc | 96 + asciidoc/_includes/ex-verse.adoc | 24 + asciidoc/_includes/ex-video.adoc | 27 + asciidoc/_includes/ex-xref.adoc | 98 + asciidoc/_includes/example.adoc | 16 + asciidoc/_includes/exten-block-compound.adoc | 59 + asciidoc/_includes/exten-block.adoc | 48 + asciidoc/_includes/exten-docinfo.adoc | 39 + asciidoc/_includes/exten-in-macro.adoc | 51 + asciidoc/_includes/exten-include.adoc | 52 + asciidoc/_includes/exten-intro.adoc | 23 + asciidoc/_includes/exten-macro.adoc | 51 + asciidoc/_includes/exten-point.adoc | 68 + asciidoc/_includes/exten-post.adoc | 36 + asciidoc/_includes/exten-pre.adoc | 69 + asciidoc/_includes/exten-tree.adoc | 86 + asciidoc/_includes/factory-apply.adoc | 30 + asciidoc/_includes/factory-gen.adoc | 45 + asciidoc/_includes/factory-intro.adoc | 12 + asciidoc/_includes/factory-preview.adoc | 17 + asciidoc/_includes/factory-setup.adoc | 49 + asciidoc/_includes/file-output.adoc | 36 + asciidoc/_includes/footnote.adoc | 94 + asciidoc/_includes/formatting-marks.adoc | 247 + asciidoc/_includes/glossary.adoc | 18 + asciidoc/_includes/header-intro.adoc | 38 + asciidoc/_includes/header-title.adoc | 108 + asciidoc/_includes/hr.adoc | 37 + asciidoc/_includes/html-code-styles.adoc | 21 + asciidoc/_includes/html-command-line.adoc | 47 + asciidoc/_includes/html-manage-images.adoc | 29 + asciidoc/_includes/html-ruby-api.adoc | 28 + asciidoc/_includes/html-styles.adoc | 42 + asciidoc/_includes/icons.adoc | 386 + asciidoc/_includes/image-position.adoc | 167 + asciidoc/_includes/image-sizing.adoc | 152 + asciidoc/_includes/image-svg.adoc | 64 + asciidoc/_includes/image-url.adoc | 44 + asciidoc/_includes/image.adoc | 58 + asciidoc/_includes/imagesdir.adoc | 38 + asciidoc/_includes/include-directive.adoc | 226 + asciidoc/_includes/include-lines-tags.adoc | 167 + asciidoc/_includes/include-list-content.adoc | 34 + asciidoc/_includes/indent-include.adoc | 55 + asciidoc/_includes/index.adoc | 71 + .../install-upgrade-asciidoctor.adoc | 143 + asciidoc/_includes/io-piping.adoc | 46 + asciidoc/_includes/language-support.adoc | 159 + asciidoc/_includes/listing-wrap.adoc | 45 + asciidoc/_includes/listing.adoc | 77 + asciidoc/_includes/literal.adoc | 59 + asciidoc/_includes/load-convert-api.adoc | 31 + asciidoc/_includes/manpage.adoc | 109 + asciidoc/_includes/messages.adoc | 282 + asciidoc/_includes/meta.adoc | 59 + .../migrating-from-asciidoc-python.adoc | 364 + asciidoc/_includes/multi-special-ex.adoc | 76 + asciidoc/_includes/multiple-include.adoc | 36 + asciidoc/_includes/mysample-data-uri.adoc | 15 + asciidoc/_includes/mysample-link.adoc | 11 + .../_includes/mysample-stylesdir-link.adoc | 13 + asciidoc/_includes/mysample-stylesdir.adoc | 12 + asciidoc/_includes/mysample-stylesheet.adoc | 11 + asciidoc/_includes/mysample.adoc | 10 + asciidoc/_includes/o-list-nest.adoc | 57 + asciidoc/_includes/o-list-num.adoc | 89 + asciidoc/_includes/o-list.adoc | 67 + asciidoc/_includes/open.adoc | 45 + asciidoc/_includes/output-format.adoc | 38 + asciidoc/_includes/page-break.adoc | 9 + asciidoc/_includes/para-align.adoc | 12 + asciidoc/_includes/para-lead.adoc | 31 + asciidoc/_includes/para-line-break.adoc | 42 + asciidoc/_includes/para.adoc | 24 + asciidoc/_includes/pass-block.adoc | 41 + asciidoc/_includes/pass-intro.adoc | 13 + asciidoc/_includes/pass-macro.adoc | 133 + asciidoc/_includes/preamble-tut.adoc | 23 + asciidoc/_includes/preamble.adoc | 14 + asciidoc/_includes/preface.adoc | 79 + asciidoc/_includes/process-intro.adoc | 15 + asciidoc/_includes/process-multi.adoc | 66 + asciidoc/_includes/project-author.adoc | 12 + asciidoc/_includes/project-lic.adoc | 10 + asciidoc/_includes/quote-alt.adoc | 67 + asciidoc/_includes/quote.adoc | 59 + asciidoc/_includes/relative-include.adoc | 24 + asciidoc/_includes/require-asciidoctor.adoc | 9 + asciidoc/_includes/revision.adoc | 59 + asciidoc/_includes/ruby-api-options.adoc | 166 + asciidoc/_includes/section-styles.adoc | 33 + asciidoc/_includes/sections.adoc | 288 + asciidoc/_includes/secure-api.adoc | 20 + asciidoc/_includes/secure-attr.adoc | 44 + asciidoc/_includes/secure-cli.adoc | 20 + asciidoc/_includes/secure.adoc | 85 + asciidoc/_includes/sidebar.adoc | 21 + asciidoc/_includes/src-coderay.adoc | 129 + asciidoc/_includes/src-highlightjs.adoc | 29 + asciidoc/_includes/src-pygments.adoc | 162 + asciidoc/_includes/src-rouge.adoc | 107 + asciidoc/_includes/src.adoc | 183 + asciidoc/_includes/static-awe.adoc | 31 + asciidoc/_includes/static-front.adoc | 31 + asciidoc/_includes/stem.adoc | 192 + asciidoc/_includes/string-api.adoc | 88 + asciidoc/_includes/structure-intro.adoc | 8 + asciidoc/_includes/subs-apply.adoc | 118 + asciidoc/_includes/subs-attr.adoc | 50 + asciidoc/_includes/subs-group-table.adoc | 51 + asciidoc/_includes/subs-macro.adoc | 51 + asciidoc/_includes/subs-post.adoc | 50 + asciidoc/_includes/subs-prevent.adoc | 23 + asciidoc/_includes/subs-quote.adoc | 101 + asciidoc/_includes/subs-repl.adoc | 99 + asciidoc/_includes/subs-specchar.adoc | 22 + asciidoc/_includes/subs-symbol-repl.adoc | 75 + asciidoc/_includes/subs.adoc | 51 + asciidoc/_includes/subtitle.adoc | 71 + asciidoc/_includes/sum-audio.adoc | 16 + asciidoc/_includes/sum-header.adoc | 135 + asciidoc/_includes/sum-image.adoc | 87 + asciidoc/_includes/sum-section.adoc | 48 + asciidoc/_includes/sum-table.adoc | 180 + asciidoc/_includes/sum-toc.adoc | 48 + asciidoc/_includes/sum-url.adoc | 37 + asciidoc/_includes/sum-video.adoc | 58 + asciidoc/_includes/table-cell.adoc | 122 + asciidoc/_includes/table-col.adoc | 283 + asciidoc/_includes/table-data.adoc | 241 + asciidoc/_includes/table-formatting.adoc | 422 + asciidoc/_includes/table.adoc | 109 + asciidoc/_includes/templates-api.adoc | 25 + asciidoc/_includes/text-bold-italic.adoc | 24 + asciidoc/_includes/text-css.adoc | 58 + asciidoc/_includes/text-editor.adoc | 23 + asciidoc/_includes/text-mono.adoc | 187 + asciidoc/_includes/text-quote-apos.adoc | 91 + asciidoc/_includes/text-sub-sup.adoc | 26 + asciidoc/_includes/text.adoc | 28 + asciidoc/_includes/toc-custom.adoc | 43 + asciidoc/_includes/toc-embeddable-html.adoc | 20 + asciidoc/_includes/toc-intro.adoc | 35 + asciidoc/_includes/toc-layout.adoc | 60 + asciidoc/_includes/toc-left.adoc | 17 + asciidoc/_includes/toc-level.adoc | 22 + asciidoc/_includes/toc-macro.adoc | 11 + asciidoc/_includes/toc-title.adoc | 10 + asciidoc/_includes/toc.adoc | 9 + asciidoc/_includes/tracks.csv | 5 + asciidoc/_includes/troubleshoot.adoc | 18 + asciidoc/_includes/ts-block-render.adoc | 22 + asciidoc/_includes/ts-url-format.adoc | 54 + asciidoc/_includes/ui.adoc | 62 + asciidoc/_includes/ulist-complex.adoc | 171 + asciidoc/_includes/ulist-marker.adoc | 35 + asciidoc/_includes/ulist-nested.adoc | 38 + asciidoc/_includes/ulist.adoc | 63 + asciidoc/_includes/uri-include.adoc | 63 + asciidoc/_includes/url-relative.adoc | 33 + asciidoc/_includes/url.adoc | 150 + asciidoc/_includes/verse.adoc | 32 + asciidoc/_includes/video.adoc | 68 + asciidoc/_includes/xhtml.adoc | 31 + asciidoc/_includes/xref-anchor.adoc | 111 + asciidoc/_includes/xref-interdoc.adoc | 61 + asciidoc/_includes/xref-relative.adoc | 39 + asciidoc/_includes/xref-source-to-source.adoc | 49 + asciidoc/_includes/xref-validate.adoc | 24 + asciidoc/_includes/xref.adoc | 62 + asciidoc/_includes/xrefstyle.adoc | 123 + 255 files changed, 27392 insertions(+) create mode 100644 asciidoc/AsciiDocSyntaxQuickReference.adoc create mode 100644 asciidoc/_includes/about-asciidoctor.adoc create mode 100644 asciidoc/_includes/abstract.adoc create mode 100644 asciidoc/_includes/admonition.adoc create mode 100644 asciidoc/_includes/api-intro.adoc create mode 100644 asciidoc/_includes/appendix.adoc create mode 100644 asciidoc/_includes/apply-theme.adoc create mode 100644 asciidoc/_includes/asciidoc-article-template.adoc create mode 100644 asciidoc/_includes/asciidoctor-ant.adoc create mode 100644 asciidoc/_includes/attr-doc.adoc create mode 100644 asciidoc/_includes/attr-element.adoc create mode 100644 asciidoc/_includes/attr-miss.adoc create mode 100644 asciidoc/_includes/attr-style.adoc create mode 100644 asciidoc/_includes/attr-use.adoc create mode 100644 asciidoc/_includes/attr.adoc create mode 100644 asciidoc/_includes/attrs-builtin.adoc create mode 100644 asciidoc/_includes/attrs-charref.adoc create mode 100644 asciidoc/_includes/attrs-env.adoc create mode 100644 asciidoc/_includes/author.adoc create mode 100644 asciidoc/_includes/benefits.adoc create mode 100644 asciidoc/_includes/biblio.adoc create mode 100644 asciidoc/_includes/block-name-table.adoc create mode 100644 asciidoc/_includes/block.adoc create mode 100644 asciidoc/_includes/book-part.adoc create mode 100644 asciidoc/_includes/callout-copy.adoc create mode 100644 asciidoc/_includes/callout-icon.adoc create mode 100644 asciidoc/_includes/callout-intro.adoc create mode 100644 asciidoc/_includes/callout-xml.adoc create mode 100644 asciidoc/_includes/checklist.adoc create mode 100644 asciidoc/_includes/cli-options.adoc create mode 100644 asciidoc/_includes/colophon.adoc create mode 100644 asciidoc/_includes/command-line-usage.adoc create mode 100644 asciidoc/_includes/comment.adoc create mode 100644 asciidoc/_includes/conditional-preprocessor-directives.adoc create mode 100644 asciidoc/_includes/convert-from-confluence-xhtml.adoc create mode 100644 asciidoc/_includes/counter.adoc create mode 100644 asciidoc/_includes/create-theme.adoc create mode 100644 asciidoc/_includes/dedication.adoc create mode 100644 asciidoc/_includes/discrete-heading.adoc create mode 100644 asciidoc/_includes/dlist-qa.adoc create mode 100644 asciidoc/_includes/dlist.adoc create mode 100644 asciidoc/_includes/docbook.adoc create mode 100644 asciidoc/_includes/docbookrx.adoc create mode 100644 asciidoc/_includes/docinfo.adoc create mode 100644 asciidoc/_includes/doctype.adoc create mode 100644 asciidoc/_includes/element.adoc create mode 100644 asciidoc/_includes/ex-admon.adoc create mode 100644 asciidoc/_includes/ex-appendix.adoc create mode 100644 asciidoc/_includes/ex-author.adoc create mode 100644 asciidoc/_includes/ex-biblio.adoc create mode 100644 asciidoc/_includes/ex-block.adoc create mode 100644 asciidoc/_includes/ex-callout.adoc create mode 100644 asciidoc/_includes/ex-comment.adoc create mode 100644 asciidoc/_includes/ex-counter.adoc create mode 100644 asciidoc/_includes/ex-desc.adoc create mode 100644 asciidoc/_includes/ex-dlist.adoc create mode 100644 asciidoc/_includes/ex-example.adoc create mode 100644 asciidoc/_includes/ex-footnote.adoc create mode 100644 asciidoc/_includes/ex-header-attr.adoc create mode 100644 asciidoc/_includes/ex-header-title.adoc create mode 100644 asciidoc/_includes/ex-hr.adoc create mode 100644 asciidoc/_includes/ex-image.adoc create mode 100644 asciidoc/_includes/ex-include.adoc create mode 100644 asciidoc/_includes/ex-keyword.adoc create mode 100644 asciidoc/_includes/ex-listing.adoc create mode 100644 asciidoc/_includes/ex-literal.adoc create mode 100644 asciidoc/_includes/ex-manpage.adoc create mode 100644 asciidoc/_includes/ex-o-list.adoc create mode 100644 asciidoc/_includes/ex-open.adoc create mode 100644 asciidoc/_includes/ex-pass.adoc create mode 100644 asciidoc/_includes/ex-quote.adoc create mode 100644 asciidoc/_includes/ex-rev.adoc create mode 100644 asciidoc/_includes/ex-section.adoc create mode 100644 asciidoc/_includes/ex-sidebar.adoc create mode 100644 asciidoc/_includes/ex-src.adoc create mode 100644 asciidoc/_includes/ex-stem.adoc create mode 100644 asciidoc/_includes/ex-subs.adoc create mode 100644 asciidoc/_includes/ex-table-cell.adoc create mode 100644 asciidoc/_includes/ex-table-data.adoc create mode 100644 asciidoc/_includes/ex-table.adoc create mode 100644 asciidoc/_includes/ex-text.adoc create mode 100644 asciidoc/_includes/ex-toc.adoc create mode 100644 asciidoc/_includes/ex-ui.adoc create mode 100644 asciidoc/_includes/ex-ulist.adoc create mode 100644 asciidoc/_includes/ex-url.adoc create mode 100644 asciidoc/_includes/ex-verse.adoc create mode 100644 asciidoc/_includes/ex-video.adoc create mode 100644 asciidoc/_includes/ex-xref.adoc create mode 100644 asciidoc/_includes/example.adoc create mode 100644 asciidoc/_includes/exten-block-compound.adoc create mode 100644 asciidoc/_includes/exten-block.adoc create mode 100644 asciidoc/_includes/exten-docinfo.adoc create mode 100644 asciidoc/_includes/exten-in-macro.adoc create mode 100644 asciidoc/_includes/exten-include.adoc create mode 100644 asciidoc/_includes/exten-intro.adoc create mode 100644 asciidoc/_includes/exten-macro.adoc create mode 100644 asciidoc/_includes/exten-point.adoc create mode 100644 asciidoc/_includes/exten-post.adoc create mode 100644 asciidoc/_includes/exten-pre.adoc create mode 100644 asciidoc/_includes/exten-tree.adoc create mode 100644 asciidoc/_includes/factory-apply.adoc create mode 100644 asciidoc/_includes/factory-gen.adoc create mode 100644 asciidoc/_includes/factory-intro.adoc create mode 100644 asciidoc/_includes/factory-preview.adoc create mode 100644 asciidoc/_includes/factory-setup.adoc create mode 100644 asciidoc/_includes/file-output.adoc create mode 100644 asciidoc/_includes/footnote.adoc create mode 100644 asciidoc/_includes/formatting-marks.adoc create mode 100644 asciidoc/_includes/glossary.adoc create mode 100644 asciidoc/_includes/header-intro.adoc create mode 100644 asciidoc/_includes/header-title.adoc create mode 100644 asciidoc/_includes/hr.adoc create mode 100644 asciidoc/_includes/html-code-styles.adoc create mode 100644 asciidoc/_includes/html-command-line.adoc create mode 100644 asciidoc/_includes/html-manage-images.adoc create mode 100644 asciidoc/_includes/html-ruby-api.adoc create mode 100644 asciidoc/_includes/html-styles.adoc create mode 100644 asciidoc/_includes/icons.adoc create mode 100644 asciidoc/_includes/image-position.adoc create mode 100644 asciidoc/_includes/image-sizing.adoc create mode 100644 asciidoc/_includes/image-svg.adoc create mode 100644 asciidoc/_includes/image-url.adoc create mode 100644 asciidoc/_includes/image.adoc create mode 100644 asciidoc/_includes/imagesdir.adoc create mode 100644 asciidoc/_includes/include-directive.adoc create mode 100644 asciidoc/_includes/include-lines-tags.adoc create mode 100644 asciidoc/_includes/include-list-content.adoc create mode 100644 asciidoc/_includes/indent-include.adoc create mode 100644 asciidoc/_includes/index.adoc create mode 100644 asciidoc/_includes/install-upgrade-asciidoctor.adoc create mode 100644 asciidoc/_includes/io-piping.adoc create mode 100644 asciidoc/_includes/language-support.adoc create mode 100644 asciidoc/_includes/listing-wrap.adoc create mode 100644 asciidoc/_includes/listing.adoc create mode 100644 asciidoc/_includes/literal.adoc create mode 100644 asciidoc/_includes/load-convert-api.adoc create mode 100644 asciidoc/_includes/manpage.adoc create mode 100644 asciidoc/_includes/messages.adoc create mode 100644 asciidoc/_includes/meta.adoc create mode 100644 asciidoc/_includes/migrating-from-asciidoc-python.adoc create mode 100644 asciidoc/_includes/multi-special-ex.adoc create mode 100644 asciidoc/_includes/multiple-include.adoc create mode 100644 asciidoc/_includes/mysample-data-uri.adoc create mode 100644 asciidoc/_includes/mysample-link.adoc create mode 100644 asciidoc/_includes/mysample-stylesdir-link.adoc create mode 100644 asciidoc/_includes/mysample-stylesdir.adoc create mode 100644 asciidoc/_includes/mysample-stylesheet.adoc create mode 100644 asciidoc/_includes/mysample.adoc create mode 100644 asciidoc/_includes/o-list-nest.adoc create mode 100644 asciidoc/_includes/o-list-num.adoc create mode 100644 asciidoc/_includes/o-list.adoc create mode 100644 asciidoc/_includes/open.adoc create mode 100644 asciidoc/_includes/output-format.adoc create mode 100644 asciidoc/_includes/page-break.adoc create mode 100644 asciidoc/_includes/para-align.adoc create mode 100644 asciidoc/_includes/para-lead.adoc create mode 100644 asciidoc/_includes/para-line-break.adoc create mode 100644 asciidoc/_includes/para.adoc create mode 100644 asciidoc/_includes/pass-block.adoc create mode 100644 asciidoc/_includes/pass-intro.adoc create mode 100644 asciidoc/_includes/pass-macro.adoc create mode 100644 asciidoc/_includes/preamble-tut.adoc create mode 100644 asciidoc/_includes/preamble.adoc create mode 100644 asciidoc/_includes/preface.adoc create mode 100644 asciidoc/_includes/process-intro.adoc create mode 100644 asciidoc/_includes/process-multi.adoc create mode 100644 asciidoc/_includes/project-author.adoc create mode 100644 asciidoc/_includes/project-lic.adoc create mode 100644 asciidoc/_includes/quote-alt.adoc create mode 100644 asciidoc/_includes/quote.adoc create mode 100644 asciidoc/_includes/relative-include.adoc create mode 100644 asciidoc/_includes/require-asciidoctor.adoc create mode 100644 asciidoc/_includes/revision.adoc create mode 100644 asciidoc/_includes/ruby-api-options.adoc create mode 100644 asciidoc/_includes/section-styles.adoc create mode 100644 asciidoc/_includes/sections.adoc create mode 100644 asciidoc/_includes/secure-api.adoc create mode 100644 asciidoc/_includes/secure-attr.adoc create mode 100644 asciidoc/_includes/secure-cli.adoc create mode 100644 asciidoc/_includes/secure.adoc create mode 100644 asciidoc/_includes/sidebar.adoc create mode 100644 asciidoc/_includes/src-coderay.adoc create mode 100644 asciidoc/_includes/src-highlightjs.adoc create mode 100644 asciidoc/_includes/src-pygments.adoc create mode 100644 asciidoc/_includes/src-rouge.adoc create mode 100644 asciidoc/_includes/src.adoc create mode 100644 asciidoc/_includes/static-awe.adoc create mode 100644 asciidoc/_includes/static-front.adoc create mode 100644 asciidoc/_includes/stem.adoc create mode 100644 asciidoc/_includes/string-api.adoc create mode 100644 asciidoc/_includes/structure-intro.adoc create mode 100644 asciidoc/_includes/subs-apply.adoc create mode 100644 asciidoc/_includes/subs-attr.adoc create mode 100644 asciidoc/_includes/subs-group-table.adoc create mode 100644 asciidoc/_includes/subs-macro.adoc create mode 100644 asciidoc/_includes/subs-post.adoc create mode 100644 asciidoc/_includes/subs-prevent.adoc create mode 100644 asciidoc/_includes/subs-quote.adoc create mode 100644 asciidoc/_includes/subs-repl.adoc create mode 100644 asciidoc/_includes/subs-specchar.adoc create mode 100644 asciidoc/_includes/subs-symbol-repl.adoc create mode 100644 asciidoc/_includes/subs.adoc create mode 100644 asciidoc/_includes/subtitle.adoc create mode 100644 asciidoc/_includes/sum-audio.adoc create mode 100644 asciidoc/_includes/sum-header.adoc create mode 100644 asciidoc/_includes/sum-image.adoc create mode 100644 asciidoc/_includes/sum-section.adoc create mode 100644 asciidoc/_includes/sum-table.adoc create mode 100644 asciidoc/_includes/sum-toc.adoc create mode 100644 asciidoc/_includes/sum-url.adoc create mode 100644 asciidoc/_includes/sum-video.adoc create mode 100644 asciidoc/_includes/table-cell.adoc create mode 100644 asciidoc/_includes/table-col.adoc create mode 100644 asciidoc/_includes/table-data.adoc create mode 100644 asciidoc/_includes/table-formatting.adoc create mode 100644 asciidoc/_includes/table.adoc create mode 100644 asciidoc/_includes/templates-api.adoc create mode 100644 asciidoc/_includes/text-bold-italic.adoc create mode 100644 asciidoc/_includes/text-css.adoc create mode 100644 asciidoc/_includes/text-editor.adoc create mode 100644 asciidoc/_includes/text-mono.adoc create mode 100644 asciidoc/_includes/text-quote-apos.adoc create mode 100644 asciidoc/_includes/text-sub-sup.adoc create mode 100644 asciidoc/_includes/text.adoc create mode 100644 asciidoc/_includes/toc-custom.adoc create mode 100644 asciidoc/_includes/toc-embeddable-html.adoc create mode 100644 asciidoc/_includes/toc-intro.adoc create mode 100644 asciidoc/_includes/toc-layout.adoc create mode 100644 asciidoc/_includes/toc-left.adoc create mode 100644 asciidoc/_includes/toc-level.adoc create mode 100644 asciidoc/_includes/toc-macro.adoc create mode 100644 asciidoc/_includes/toc-title.adoc create mode 100644 asciidoc/_includes/toc.adoc create mode 100644 asciidoc/_includes/tracks.csv create mode 100644 asciidoc/_includes/troubleshoot.adoc create mode 100644 asciidoc/_includes/ts-block-render.adoc create mode 100644 asciidoc/_includes/ts-url-format.adoc create mode 100644 asciidoc/_includes/ui.adoc create mode 100644 asciidoc/_includes/ulist-complex.adoc create mode 100644 asciidoc/_includes/ulist-marker.adoc create mode 100644 asciidoc/_includes/ulist-nested.adoc create mode 100644 asciidoc/_includes/ulist.adoc create mode 100644 asciidoc/_includes/uri-include.adoc create mode 100644 asciidoc/_includes/url-relative.adoc create mode 100644 asciidoc/_includes/url.adoc create mode 100644 asciidoc/_includes/verse.adoc create mode 100644 asciidoc/_includes/video.adoc create mode 100644 asciidoc/_includes/xhtml.adoc create mode 100644 asciidoc/_includes/xref-anchor.adoc create mode 100644 asciidoc/_includes/xref-interdoc.adoc create mode 100644 asciidoc/_includes/xref-relative.adoc create mode 100644 asciidoc/_includes/xref-source-to-source.adoc create mode 100644 asciidoc/_includes/xref-validate.adoc create mode 100644 asciidoc/_includes/xref.adoc create mode 100644 asciidoc/_includes/xrefstyle.adoc diff --git a/asciidoc/AsciiDocSyntaxQuickReference.adoc b/asciidoc/AsciiDocSyntaxQuickReference.adoc new file mode 100644 index 0000000..523477a --- /dev/null +++ b/asciidoc/AsciiDocSyntaxQuickReference.adoc @@ -0,0 +1,8002 @@ += AsciiDoc Syntax Quick Reference ! +Apostolos rootApostolos@swarmlab.io +// Metadata: +:description: Intro and Install +:keywords: AsciiDoc Syntax Quick Reference +:includedir: _includes +:data-uri: +:toc: right +:toc-title: Πίνακας περιεχομένων +:toclevels: 4 +:source-highlighter: highlight +:icons: font +:sectnums: + + +include::header.adoc[] + +{empty} + + + + +[[cheat-Ascii]] +== Install (swarmlab-adoc) + +https://git.swarmlab.io:3000/swarmlab/swarmlab-adoc[^] + + +[[cheat-useadoc]] +== AsciiDoc Syntax Quick Reference + + + +[NOTE] +==== +These examples focus on the output generated by the HTML backend. +AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. +==== + +toc::[] + +== Paragraphs + +.Normal +---- +include::{includedir}/ex-text.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-para] +==== + +.Literal +---- +include::{includedir}/ex-literal.adoc[tag=b-imp] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp] +==== + +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-admon.adoc[tag=b-para] +==== + +NOTE: You can also create <>. + +.Lead paragraph +---- +include::{includedir}/ex-text.adoc[tag=b-lead] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-lead] +==== + +NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. + +.More Paragraph, Admonition and Literal Block Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-para}[Paragraphs] +* {uri-literal}[Literal Text and Blocks] +* {uri-admon}[Admonitions] +**** + +== Formatted Text + +.Bold, Italic, and Monospace +---- +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +==== + +.Monospace vs codespan +---- +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +==== + +NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. +Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. +See the <> for details. + +.Marks and Custom Styling +---- +include::{includedir}/ex-text.adoc[tag=css-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=css-all] +==== + +.Superscript and Subscript +---- +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +==== + +.Curved Quotation Marks and Apostrophes (Smart Quotes) +---- +include::{includedir}/ex-text.adoc[tag=b-c-quote] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-c-quote] +==== + +.More Text Formatting Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-bold}[Bold and Italic Formatting] +* {uri-quote}[Quotation Marks and Apostrophes] +* {uri-sub}[Subscript and Superscript] +* {uri-mono}[Monospace Formatting] +* {uri-css}[Custom Styling with Attributes] +* {uri-pass}[Passthrough Macros] +**** + +== Document Header + +IMPORTANT: A header is optional. + +CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. + +.Title only +---- +include::{includedir}/ex-header-title.adoc[tag=b-base] +---- + +.Title and author line +---- +include::{includedir}/ex-author.adoc[tag=b-base] +---- + +TIP: Asciidoctor allows multiple authors in the author line. +Use the semi-colon character to separate each author. + +.Title, author line and revision line +---- +include::{includedir}/ex-rev.adoc[tag=b-base] +---- + +IMPORTANT: You cannot have a revision line without an author line. + +.Document header with attributes +---- +include::{includedir}/ex-header-attr.adoc[tag=b-base] +---- + +[#section-titles] +== Section Titles (Headings) + +.Article doctype +---- +include::{includedir}/ex-section.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-base] +==== + +WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. + +NOTE: The number of equal signs matches the heading level in the HTML output. +For example, _Section Level 1_ becomes an `

` heading. + +.Book doctype +---- +include::{includedir}/ex-section.adoc[tag=book] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-book] +==== + +//// +IMPORTANT: There are two other ways to define a section title. +_Their omission is intentional_. +They both require more markup and are therefore unnecessary. +The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. +The reader never sees the extra markup, so why type it? +*Be frugal!* +//// + +.Explicit id +---- +[#primitives-nulls] +== Primitive types and null values +---- + +.Section anchors and links (Asciidoctor only) + +`sectanchors`:: +When this document attribute is set, a section icon anchor appears in front of the section title. + +`sectlinks`:: +When this document attribute is set, the section titles become self-links. +This enables a reader to bookmark the section. + +NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. + +== Include Files + +.Document parts +---- +include::{includedir}/ex-include.adoc[tag=base] +---- + +CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. +Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. + +.Include content from a URI +---- +include::{includedir}/ex-include.adoc[tag=uri] +---- + +NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. +Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. + +== Breaks + +.Hard line break +---- +include::{includedir}/ex-text.adoc[tag=hb-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=hb-all] +==== + +.Thematic break (aka horizontal rule) +---- +include::{includedir}/ex-hr.adoc[tag=in-between] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=in-between] +==== + +.Page break +---- +<<< +---- + +== Lists + +.Unordered, basic +---- +include::{includedir}/ex-ulist.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base] +==== + +.Unordered, basic (alt) +---- +include::{includedir}/ex-ulist.adoc[tag=base-alt] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base-alt] +==== + +NOTE: A blank line is required before and after a list to separated it from other blocks. + +TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. +The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. + +.Unordered, max nesting +---- +include::{includedir}/ex-ulist.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=max] +==== + +TIP: The unordered list marker can be changed using {uri-marker}[block styles]. + +.Ordered, basic +---- +include::{includedir}/ex-o-list.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=b-base] +==== + +NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. + +.Ordered, nested +---- +include::{includedir}/ex-o-list.adoc[tag=nest] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=nest] +==== + +.Ordered, max nesting +---- +include::{includedir}/ex-o-list.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=max] +==== + +TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. + +.Checklist +---- +include::{includedir}/ex-ulist.adoc[tag=check] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=check] +==== + +TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. + +.Description, single-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base] +==== + +.Description, multi-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +==== + +.Q&A +---- +include::{includedir}/ex-dlist.adoc[tag=qa] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=qa] +==== + +.Mixed +---- +include::{includedir}/ex-dlist.adoc[tag=3-mix] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=3-mix] +==== + +TIP: Lists can be indented. +Leading whitespace is not significant. + +.Complex content in outline lists +---- +include::{includedir}/ex-ulist.adoc[tag=b-complex] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=b-complex] +==== + +== Links + +.External +---- +include::{includedir}/ex-url.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-base] +==== + +.With spaces and special characters +---- +include::{includedir}/ex-url.adoc[tag=b-spaces] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-spaces] +==== + +.Windows path +---- +include::{includedir}/ex-url.adoc[tag=b-windows] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-windows] +==== + +.Relative +---- +link:index.html[Docs] +---- + +[.result] +==== +link:index.html[Docs] +==== + +.Email and IRC +---- +include::{includedir}/ex-url.adoc[tag=b-scheme] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-scheme] +==== + +.Link with attributes (Asciidoctor only) +---- +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +==== + +NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. +To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. +Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. +When attribute parsing is enabled, you must quote the link text if it contains a comma. + +.Inline anchors +---- +include::{includedir}/ex-xref.adoc[tag=anchor] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=anchor] +==== + +.Internal cross references +---- +include::{includedir}/ex-xref.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=b-base] +==== + +.Inter-document cross references (Asciidoctor only) +---- +include::{includedir}/ex-xref.adoc[tag=b-inter] +---- + +== Images + +Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. +You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. + +The `imagesdir` attribute can be an absolute path, relative path, or base URL. +When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. + +.Block +---- +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +==== + +.Inline +---- +include::{includedir}/ex-image.adoc[tag=in] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in] +==== + +IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. +(All macros follow this pattern). +You use an inline image when you need to place the image in a line of text. +Otherwise, you should prefer the block form. + +.Inline image with positioning role +---- +include::{includedir}/ex-image.adoc[tag=in-role] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in-role] +==== + +TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. + +.Embedded +---- +include::{includedir}/ex-image.adoc[tag=data] +---- + +NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. + +TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. + +== Videos + +.Block +---- +include::{includedir}/ex-video.adoc[tag=base] + +include::{includedir}/ex-video.adoc[tag=attr] +---- + +.Embedded Youtube video +---- +include::{includedir}/ex-video.adoc[tag=you] +---- + +.Embedded Vimeo video +---- +include::{includedir}/ex-video.adoc[tag=vim] +---- + +TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. + +== Source Code + +.Inline (monospace only) +---- +include::{includedir}/ex-text.adoc[tag=b-mono-code] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-mono-code] +==== + +.Inline (literal) +---- +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +==== + +.Literal line +---- +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +==== + +.Literal block +---- +include::{includedir}/ex-literal.adoc[tag=b-block] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-block] +==== + +[listing] +.Listing block with title, no syntax highlighting +.... +include::{includedir}/ex-listing.adoc[tag=b-base] +.... + +[.result] +==== +include::{includedir}/ex-listing.adoc[tag=b-base] +==== + +[listing] +.Code block with title and syntax highlighting +.... +include::{includedir}/ex-src.adoc[tag=src-base] +.... + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-base] +==== + +[listing,subs=specialchars] +.Code block with callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-src] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-src] +==== + +[listing,subs=specialchars] +.Code block with non-selectable callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +==== + +[listing,subs=specialchars] +.XML code block with a non-selectable callout +.... +include::{includedir}/ex-callout.adoc[tag=source-xml] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=source-xml] +==== + +[listing] +.Code block sourced from file +.... +include::{includedir}/ex-src.adoc[tag=src-inc] +.... + +[listing] +.Code block sourced from file relative to source directory +.... +include::{includedir}/ex-src.adoc[tag=rel] +.... + +[listing] +.Strip leading indentation from source +.... +include::{includedir}/ex-src.adoc[tag=ind] +.... + +[NOTE] +==== +* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). +* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. +==== + +.Code block without delimiters (no blank lines) +---- +include::{includedir}/ex-src.adoc[tag=src-para] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-para] +==== + +[IMPORTANT] +.Enabling the syntax highlighter +==== +Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. + + :source-highlighter: pygments + +The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. +==== + +== More Delimited Blocks + +.Sidebar +---- +include::{includedir}/ex-sidebar.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-sidebar.adoc[tag=base] +==== + +NOTE: Any block can have a title, positioned above the block. +A block title is a line of text that starts with a dot. +The dot cannot be followed by a space. + +.Example +---- +include::{includedir}/ex-example.adoc[tag=base] +---- + +[example.result] +-- +include::{includedir}/ex-example.adoc[tag=base] +-- + +[#admon-bl] +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-bl] +---- + +[.result] +===== +include::{includedir}/ex-admon.adoc[tag=b-bl] +===== + +[TIP] +.Admonition and callout icons +==== +Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. + +To use this feature, set the value of the `icons` document attribute to `font`. +Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. + +Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. +==== + +.Blockquote +---- +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +==== + +.Abbreviated blockquote (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=abbr] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=abbr] +==== + +.Air quotes: the best thing since fenced code blocks (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=air] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=air] +==== + +.Passthrough +---- +include::{includedir}/ex-pass.adoc[tag=b-bl] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-bl] +==== + +.Open +---- +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +---- + +[.result] +==== +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +==== + +[listing] +.Custom substitutions +.... +include::{includedir}/ex-listing.adoc[tag=subs] +.... + +[.result] +==== +// the attribute value is hard-coded in this result since the example depends +// on a hypothetical document attribute +include::{includedir}/ex-listing.adoc[tag=subs-out] +==== + +== Block Id, Role and Options + +.Traditional (longhand) markup method for assigning block id and role +---- +[[goals]] +[role="incremental"] +* Goal 1 +* Goal 2 +---- + +.Shorthand markup method for assigning block id and role (Asciidoctor only) +---- +[#goals.incremental] +* Goal 1 +* Goal 2 +---- + +[TIP] +==== +* To specify multiple roles using the shorthand syntax, separate them by dots. +* The order of `id` and `role` values in the shorthand syntax does not matter. +==== + +.Traditional (longhand) markup method for assigning quoted text anchor (id) and role +---- +[[free_the_world]][big goal]_free the world_ +---- + +.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) +---- +[#free_the_world.big.goal]_free the world_ +---- + +.Role assigned to text enclosed in backticks +---- +[.rolename]`monospace text` +---- + +.Traditional (longhand) markup method for assigning block options +---- +[options="header,footer,autowidth"] +|=== +|Cell A |Cell B +|=== +---- + +.Shorthand markup method for assigning block options (Asciidoctor only) +---- +[%header%footer%autowidth] +|=== +|Cell A |Cell B +|=== +---- + +== Comments + +.Line +---- +include::{includedir}/ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::{includedir}/ex-comment.adoc[tag=bl] +---- + +== Tables + +.Table with a title, three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-base-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-base-h] +==== +<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. +<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. + +.Table with two columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-h] +==== +<1> The `+*+` in the `cols` attribute is the repeat operator. +It means repeat the column specification across the remaining of columns. +In this case, we are repeating the default formatting across 2 columns. +When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. + +.Table with three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-indv-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-indv] +==== +<1> In this example, the `cols` attribute has two functions. +It specifies that this table has three columns, and it sets their relative widths. + +.Table with column containing AsciiDoc content +---- +include::{includedir}/ex-table.adoc[tag=b-col-a] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-a] +==== + +.Table from CSV data +---- +include::{includedir}/ex-table-data.adoc[tag=csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=csv] +==== + +.Table from CSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-csv] +==== + +.Table from CSV data in file +---- +include::{includedir}/ex-table-data.adoc[tag=i-csv] +---- + +.Table from DSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +==== + +.Table with formatted, aligned and merged cells +---- +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +---- + +[.result] +==== +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +==== + +== UI Macros + +IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. + +.Keyboard shortcuts (inline kbd macro) +---- +include::{includedir}/ex-ui.adoc[tag=key] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=key] +==== + +.Menu selections (inline menu macro) +---- +include::{includedir}/ex-ui.adoc[tag=menu] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=menu] +==== + +.Buttons (inline btn macro) +---- +include::{includedir}/ex-ui.adoc[tag=button] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=button] +==== + +== Attributes and Substitutions + +.Attribute declaration and usage +---- +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +---- + +[.result] +==== +// I have to use a nested doc hack here, otherwise the attributes won't resolve +[.unstyled] +|=== +a| +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +|=== +==== + +.Attribute assignment precedence (highest to lowest) +- Attribute passed to the API or CLI that does not end in `@` +- Attribute defined in the document +- Attribute passed to the API or CLI that ends in `@` +- Intrinsic attribute value (default values) + +TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. + +// Table of predefined attributes for character replacements +include::{includedir}/attrs-charref.adoc[tag=table] + +// Table of environment attributes +include::{includedir}/attrs-env.adoc[tag=table] + +.Named substitutions +include::{includedir}/subs-apply.adoc[tag=group] + +.Counter attributes +---- +include::{includedir}/ex-counter.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-counter.adoc[tag=base] +==== + +== Text Replacement + +// Table of text replacements performed during replacements substitution +include::{includedir}/subs-symbol-repl.adoc[] + +TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. + +== Escaping Text + +.Backslash +---- +include::{includedir}/ex-subs.adoc[tag=b-slash] +---- + +[.result] +==== +include::{includedir}/ex-subs.adoc[tag=b-slash] +==== + +.Passthrough ("`plus for passthrough`") +---- +include::{includedir}/ex-pass.adoc[tag=plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=plus] +==== + +//// +.Double dollar +---- +include::{includedir}/ex-pass.adoc[tag=b-dollar] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-dollar] +==== +//// + +.Raw (triple plus and inline pass macro) +---- +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +==== + +//// +.Backticks +---- +include::{includedir}/ex-pass.adoc[tag=b-tick] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-tick] +==== +//// + +== Table of Contents (ToC) + +.Document with ToC +---- +include::{includedir}/ex-toc.adoc[tag=base] +---- + +.Document with ToC positioned on the right +---- +include::{includedir}/ex-toc.adoc[tag=pos] +---- + +TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. + +== Bibliography + +.Bibliography with inbound references +---- +include::{includedir}/ex-biblio.adoc[tag=base] +---- + +[.result] +==== +|=== +a| +include::{includedir}/ex-biblio.adoc[tag=base] +|=== +==== + +[#section-footnotes] +== Footnotes + +.Normal and reusable footnotes +---- +include::{includedir}/ex-footnote.adoc[tag=base] +---- + +[.result] +==== +[.unstyled] +|=== +a| +include::{includedir}/ex-footnote.adoc[tag=base] +|=== +==== + +[#markdown-compatibility] +== Markdown Compatibility + +Markdown compatible syntax is only available when using Asciidoctor. + +.Markdown-style headings +---- +include::{includedir}/ex-section.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-md] +==== + +.Fenced code block with syntax highlighting +---- +include::{includedir}/ex-src.adoc[tag=fence] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=fence] +==== + +.Markdown-style blockquote +---- +include::{includedir}/ex-quote.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md] +==== + +.Markdown-style blockquote with block content +---- +include::{includedir}/ex-quote.adoc[tag=md-alt] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md-alt] +==== + +.Markdown-style horizontal rules +---- +include::{includedir}/ex-hr.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=md] +==== + +== User Manual and Help + +To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. +Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. += AsciiDoc Syntax Quick Reference +Dan Allen; Sarah White +v1.0.4, 2014-08-08 +:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. +:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet +:page-description: {description} +:page-keywords: {keywords} +:page-layout: docs +:page-javascripts: [view-result] +:imagesdir: ../images +:includedir: _includes +:experimental: +:table-caption!: +:example-caption!: +:figure-caption!: +ifndef::env-site[] +:idprefix: +:idseparator: - +:toc: macro +endif::[] +// URLs +:docs: link:../ +ifdef::env-github[:docs: https://asciidoctor.org/docs/] +:user: {docs}user-manual/ +ifdef::env-browser[] +:docs: link:index.adoc +:user: link:user-manual.adoc +endif::[] +:uri-fontawesome: https://fontawesome.com/v4.7.0/ +:uri-icon-in: {user}#inline-icons +:uri-icon-attrs: {user}#size-rotate-and-flip +:uri-video: {user}#video +:uri-checklist: {user}#checklist +:uri-marker: {user}#custom-markers +:uri-list-num: {user}#numbering-styles +:uri-imagesdir: {user}#setting-the-location-of-images +:uri-image-attrs: {user}#putting-images-in-their-place +:uri-toc: {user}#user-toc +:uri-para: {user}#paragraph +:uri-literal: {user}#literal-text-and-blocks +:uri-admon: {user}#admonition +:uri-bold: {user}#bold-and-italic +:uri-quote: {user}#curved +:uri-sub: {user}#subscript-and-superscript +:uri-mono: {user}#mono +:uri-css: {user}#custom-styling-with-attributes +:uri-pass: {user}#pass-macros +:uri-mailinglist: http://discuss.asciidoctor.org +:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references +:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs + +//// +Syntax to cover: +- preface +- index terms +- built-in attributes (such as {author}, {revision}, etc) +- start=n for ordered lists +- horizontal description list +- anchor for any block element +- block metadata (missing example of normal attributes) +- command line reference? perhaps another doc? yes + +PDF TODO: +- add license on title page (legalnotice tag) +- table cell bg +- show example of section levels +- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) +- style sidebar block +//// + +ifdef::basebackend-docbook[] +[preface] +== About +endif::basebackend-docbook[] + +AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. +{description} + +[NOTE] +==== +These examples focus on the output generated by the HTML backend. +AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. +==== + +toc::[] + +== Paragraphs + +.Normal +---- +include::{includedir}/ex-text.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-para] +==== + +.Literal +---- +include::{includedir}/ex-literal.adoc[tag=b-imp] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp] +==== + +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-admon.adoc[tag=b-para] +==== + +NOTE: You can also create <>. + +.Lead paragraph +---- +include::{includedir}/ex-text.adoc[tag=b-lead] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-lead] +==== + +NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. + +.More Paragraph, Admonition and Literal Block Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-para}[Paragraphs] +* {uri-literal}[Literal Text and Blocks] +* {uri-admon}[Admonitions] +**** + +== Formatted Text + +.Bold, Italic, and Monospace +---- +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +==== + +.Monospace vs codespan +---- +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +==== + +NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. +Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. +See the <> for details. + +.Marks and Custom Styling +---- +include::{includedir}/ex-text.adoc[tag=css-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=css-all] +==== + +.Superscript and Subscript +---- +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +==== + +.Curved Quotation Marks and Apostrophes (Smart Quotes) +---- +include::{includedir}/ex-text.adoc[tag=b-c-quote] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-c-quote] +==== + +.More Text Formatting Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-bold}[Bold and Italic Formatting] +* {uri-quote}[Quotation Marks and Apostrophes] +* {uri-sub}[Subscript and Superscript] +* {uri-mono}[Monospace Formatting] +* {uri-css}[Custom Styling with Attributes] +* {uri-pass}[Passthrough Macros] +**** + +== Document Header + +IMPORTANT: A header is optional. + +CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. + +.Title only +---- +include::{includedir}/ex-header-title.adoc[tag=b-base] +---- + +.Title and author line +---- +include::{includedir}/ex-author.adoc[tag=b-base] +---- + +TIP: Asciidoctor allows multiple authors in the author line. +Use the semi-colon character to separate each author. + +.Title, author line and revision line +---- +include::{includedir}/ex-rev.adoc[tag=b-base] +---- + +IMPORTANT: You cannot have a revision line without an author line. + +.Document header with attributes +---- +include::{includedir}/ex-header-attr.adoc[tag=b-base] +---- + +[#section-titles] +== Section Titles (Headings) + +.Article doctype +---- +include::{includedir}/ex-section.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-base] +==== + +WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. + +NOTE: The number of equal signs matches the heading level in the HTML output. +For example, _Section Level 1_ becomes an `

` heading. + +.Book doctype +---- +include::{includedir}/ex-section.adoc[tag=book] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-book] +==== + +//// +IMPORTANT: There are two other ways to define a section title. +_Their omission is intentional_. +They both require more markup and are therefore unnecessary. +The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. +The reader never sees the extra markup, so why type it? +*Be frugal!* +//// + +.Explicit id +---- +[#primitives-nulls] +== Primitive types and null values +---- + +.Section anchors and links (Asciidoctor only) + +`sectanchors`:: +When this document attribute is set, a section icon anchor appears in front of the section title. + +`sectlinks`:: +When this document attribute is set, the section titles become self-links. +This enables a reader to bookmark the section. + +NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. + +== Include Files + +.Document parts +---- +include::{includedir}/ex-include.adoc[tag=base] +---- + +CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. +Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. + +.Include content from a URI +---- +include::{includedir}/ex-include.adoc[tag=uri] +---- + +NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. +Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. + +== Breaks + +.Hard line break +---- +include::{includedir}/ex-text.adoc[tag=hb-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=hb-all] +==== + +.Thematic break (aka horizontal rule) +---- +include::{includedir}/ex-hr.adoc[tag=in-between] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=in-between] +==== + +.Page break +---- +<<< +---- + +== Lists + +.Unordered, basic +---- +include::{includedir}/ex-ulist.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base] +==== + +.Unordered, basic (alt) +---- +include::{includedir}/ex-ulist.adoc[tag=base-alt] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base-alt] +==== + +NOTE: A blank line is required before and after a list to separated it from other blocks. + +TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. +The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. + +.Unordered, max nesting +---- +include::{includedir}/ex-ulist.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=max] +==== + +TIP: The unordered list marker can be changed using {uri-marker}[block styles]. + +.Ordered, basic +---- +include::{includedir}/ex-o-list.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=b-base] +==== + +NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. + +.Ordered, nested +---- +include::{includedir}/ex-o-list.adoc[tag=nest] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=nest] +==== + +.Ordered, max nesting +---- +include::{includedir}/ex-o-list.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=max] +==== + +TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. + +.Checklist +---- +include::{includedir}/ex-ulist.adoc[tag=check] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=check] +==== + +TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. + +.Description, single-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base] +==== + +.Description, multi-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +==== + +.Q&A +---- +include::{includedir}/ex-dlist.adoc[tag=qa] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=qa] +==== + +.Mixed +---- +include::{includedir}/ex-dlist.adoc[tag=3-mix] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=3-mix] +==== + +TIP: Lists can be indented. +Leading whitespace is not significant. + +.Complex content in outline lists +---- +include::{includedir}/ex-ulist.adoc[tag=b-complex] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=b-complex] +==== + +== Links + +.External +---- +include::{includedir}/ex-url.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-base] +==== + +.With spaces and special characters +---- +include::{includedir}/ex-url.adoc[tag=b-spaces] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-spaces] +==== + +.Windows path +---- +include::{includedir}/ex-url.adoc[tag=b-windows] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-windows] +==== + +.Relative +---- +link:index.html[Docs] +---- + +[.result] +==== +link:index.html[Docs] +==== + +.Email and IRC +---- +include::{includedir}/ex-url.adoc[tag=b-scheme] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-scheme] +==== + +.Link with attributes (Asciidoctor only) +---- +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +==== + +NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. +To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. +Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. +When attribute parsing is enabled, you must quote the link text if it contains a comma. + +.Inline anchors +---- +include::{includedir}/ex-xref.adoc[tag=anchor] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=anchor] +==== + +.Internal cross references +---- +include::{includedir}/ex-xref.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=b-base] +==== + +.Inter-document cross references (Asciidoctor only) +---- +include::{includedir}/ex-xref.adoc[tag=b-inter] +---- + +== Images + +Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. +You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. + +The `imagesdir` attribute can be an absolute path, relative path, or base URL. +When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. + +.Block +---- +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +==== + +.Inline +---- +include::{includedir}/ex-image.adoc[tag=in] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in] +==== + +IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. +(All macros follow this pattern). +You use an inline image when you need to place the image in a line of text. +Otherwise, you should prefer the block form. + +.Inline image with positioning role +---- +include::{includedir}/ex-image.adoc[tag=in-role] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in-role] +==== + +TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. + +.Embedded +---- +include::{includedir}/ex-image.adoc[tag=data] +---- + +NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. + +TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. + +== Videos + +.Block +---- +include::{includedir}/ex-video.adoc[tag=base] + +include::{includedir}/ex-video.adoc[tag=attr] +---- + +.Embedded Youtube video +---- +include::{includedir}/ex-video.adoc[tag=you] +---- + +.Embedded Vimeo video +---- +include::{includedir}/ex-video.adoc[tag=vim] +---- + +TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. + +== Source Code + +.Inline (monospace only) +---- +include::{includedir}/ex-text.adoc[tag=b-mono-code] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-mono-code] +==== + +.Inline (literal) +---- +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +==== + +.Literal line +---- +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +==== + +.Literal block +---- +include::{includedir}/ex-literal.adoc[tag=b-block] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-block] +==== + +[listing] +.Listing block with title, no syntax highlighting +.... +include::{includedir}/ex-listing.adoc[tag=b-base] +.... + +[.result] +==== +include::{includedir}/ex-listing.adoc[tag=b-base] +==== + +[listing] +.Code block with title and syntax highlighting +.... +include::{includedir}/ex-src.adoc[tag=src-base] +.... + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-base] +==== + +[listing,subs=specialchars] +.Code block with callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-src] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-src] +==== + +[listing,subs=specialchars] +.Code block with non-selectable callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +==== + +[listing,subs=specialchars] +.XML code block with a non-selectable callout +.... +include::{includedir}/ex-callout.adoc[tag=source-xml] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=source-xml] +==== + +[listing] +.Code block sourced from file +.... +include::{includedir}/ex-src.adoc[tag=src-inc] +.... + +[listing] +.Code block sourced from file relative to source directory +.... +include::{includedir}/ex-src.adoc[tag=rel] +.... + +[listing] +.Strip leading indentation from source +.... +include::{includedir}/ex-src.adoc[tag=ind] +.... + +[NOTE] +==== +* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). +* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. +==== + +.Code block without delimiters (no blank lines) +---- +include::{includedir}/ex-src.adoc[tag=src-para] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-para] +==== + +[IMPORTANT] +.Enabling the syntax highlighter +==== +Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. + + :source-highlighter: pygments + +The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. +==== + +== More Delimited Blocks + +.Sidebar +---- +include::{includedir}/ex-sidebar.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-sidebar.adoc[tag=base] +==== + +NOTE: Any block can have a title, positioned above the block. +A block title is a line of text that starts with a dot. +The dot cannot be followed by a space. + +.Example +---- +include::{includedir}/ex-example.adoc[tag=base] +---- + +[example.result] +-- +include::{includedir}/ex-example.adoc[tag=base] +-- + +[#admon-bl] +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-bl] +---- + +[.result] +===== +include::{includedir}/ex-admon.adoc[tag=b-bl] +===== + +[TIP] +.Admonition and callout icons +==== +Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. + +To use this feature, set the value of the `icons` document attribute to `font`. +Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. + +Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. +==== + +.Blockquote +---- +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +==== + +.Abbreviated blockquote (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=abbr] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=abbr] +==== + +.Air quotes: the best thing since fenced code blocks (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=air] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=air] +==== + +.Passthrough +---- +include::{includedir}/ex-pass.adoc[tag=b-bl] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-bl] +==== + +.Open +---- +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +---- + +[.result] +==== +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +==== + +[listing] +.Custom substitutions +.... +include::{includedir}/ex-listing.adoc[tag=subs] +.... + +[.result] +==== +// the attribute value is hard-coded in this result since the example depends +// on a hypothetical document attribute +include::{includedir}/ex-listing.adoc[tag=subs-out] +==== + +== Block Id, Role and Options + +.Traditional (longhand) markup method for assigning block id and role +---- +[[goals]] +[role="incremental"] +* Goal 1 +* Goal 2 +---- + +.Shorthand markup method for assigning block id and role (Asciidoctor only) +---- +[#goals.incremental] +* Goal 1 +* Goal 2 +---- + +[TIP] +==== +* To specify multiple roles using the shorthand syntax, separate them by dots. +* The order of `id` and `role` values in the shorthand syntax does not matter. +==== + +.Traditional (longhand) markup method for assigning quoted text anchor (id) and role +---- +[[free_the_world]][big goal]_free the world_ +---- + +.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) +---- +[#free_the_world.big.goal]_free the world_ +---- + +.Role assigned to text enclosed in backticks +---- +[.rolename]`monospace text` +---- + +.Traditional (longhand) markup method for assigning block options +---- +[options="header,footer,autowidth"] +|=== +|Cell A |Cell B +|=== +---- + +.Shorthand markup method for assigning block options (Asciidoctor only) +---- +[%header%footer%autowidth] +|=== +|Cell A |Cell B +|=== +---- + +== Comments + +.Line +---- +include::{includedir}/ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::{includedir}/ex-comment.adoc[tag=bl] +---- + +== Tables + +.Table with a title, three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-base-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-base-h] +==== +<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. +<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. + +.Table with two columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-h] +==== +<1> The `+*+` in the `cols` attribute is the repeat operator. +It means repeat the column specification across the remaining of columns. +In this case, we are repeating the default formatting across 2 columns. +When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. + +.Table with three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-indv-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-indv] +==== +<1> In this example, the `cols` attribute has two functions. +It specifies that this table has three columns, and it sets their relative widths. + +.Table with column containing AsciiDoc content +---- +include::{includedir}/ex-table.adoc[tag=b-col-a] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-a] +==== + +.Table from CSV data +---- +include::{includedir}/ex-table-data.adoc[tag=csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=csv] +==== + +.Table from CSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-csv] +==== + +.Table from CSV data in file +---- +include::{includedir}/ex-table-data.adoc[tag=i-csv] +---- + +.Table from DSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +==== + +.Table with formatted, aligned and merged cells +---- +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +---- + +[.result] +==== +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +==== + +== UI Macros + +IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. + +.Keyboard shortcuts (inline kbd macro) +---- +include::{includedir}/ex-ui.adoc[tag=key] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=key] +==== + +.Menu selections (inline menu macro) +---- +include::{includedir}/ex-ui.adoc[tag=menu] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=menu] +==== + +.Buttons (inline btn macro) +---- +include::{includedir}/ex-ui.adoc[tag=button] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=button] +==== + +== Attributes and Substitutions + +.Attribute declaration and usage +---- +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +---- + +[.result] +==== +// I have to use a nested doc hack here, otherwise the attributes won't resolve +[.unstyled] +|=== +a| +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +|=== +==== + +.Attribute assignment precedence (highest to lowest) +- Attribute passed to the API or CLI that does not end in `@` +- Attribute defined in the document +- Attribute passed to the API or CLI that ends in `@` +- Intrinsic attribute value (default values) + +TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. + +// Table of predefined attributes for character replacements +include::{includedir}/attrs-charref.adoc[tag=table] + +// Table of environment attributes +include::{includedir}/attrs-env.adoc[tag=table] + +.Named substitutions +include::{includedir}/subs-apply.adoc[tag=group] + +.Counter attributes +---- +include::{includedir}/ex-counter.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-counter.adoc[tag=base] +==== + +== Text Replacement + +// Table of text replacements performed during replacements substitution +include::{includedir}/subs-symbol-repl.adoc[] + +TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. + +== Escaping Text + +.Backslash +---- +include::{includedir}/ex-subs.adoc[tag=b-slash] +---- + +[.result] +==== +include::{includedir}/ex-subs.adoc[tag=b-slash] +==== + +.Passthrough ("`plus for passthrough`") +---- +include::{includedir}/ex-pass.adoc[tag=plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=plus] +==== + +//// +.Double dollar +---- +include::{includedir}/ex-pass.adoc[tag=b-dollar] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-dollar] +==== +//// + +.Raw (triple plus and inline pass macro) +---- +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +==== + +//// +.Backticks +---- +include::{includedir}/ex-pass.adoc[tag=b-tick] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-tick] +==== +//// + +== Table of Contents (ToC) + +.Document with ToC +---- +include::{includedir}/ex-toc.adoc[tag=base] +---- + +.Document with ToC positioned on the right +---- +include::{includedir}/ex-toc.adoc[tag=pos] +---- + +TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. + +== Bibliography + +.Bibliography with inbound references +---- +include::{includedir}/ex-biblio.adoc[tag=base] +---- + +[.result] +==== +|=== +a| +include::{includedir}/ex-biblio.adoc[tag=base] +|=== +==== + +[#section-footnotes] +== Footnotes + +.Normal and reusable footnotes +---- +include::{includedir}/ex-footnote.adoc[tag=base] +---- + +[.result] +==== +[.unstyled] +|=== +a| +include::{includedir}/ex-footnote.adoc[tag=base] +|=== +==== + +[#markdown-compatibility] +== Markdown Compatibility + +Markdown compatible syntax is only available when using Asciidoctor. + +.Markdown-style headings +---- +include::{includedir}/ex-section.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-md] +==== + +.Fenced code block with syntax highlighting +---- +include::{includedir}/ex-src.adoc[tag=fence] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=fence] +==== + +.Markdown-style blockquote +---- +include::{includedir}/ex-quote.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md] +==== + +.Markdown-style blockquote with block content +---- +include::{includedir}/ex-quote.adoc[tag=md-alt] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md-alt] +==== + +.Markdown-style horizontal rules +---- +include::{includedir}/ex-hr.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=md] +==== + +== User Manual and Help + +To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. +Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. += AsciiDoc Syntax Quick Reference +Dan Allen; Sarah White +v1.0.4, 2014-08-08 +:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. +:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet +:page-description: {description} +:page-keywords: {keywords} +:page-layout: docs +:page-javascripts: [view-result] +:imagesdir: ../images +:includedir: _includes +:experimental: +:table-caption!: +:example-caption!: +:figure-caption!: +ifndef::env-site[] +:idprefix: +:idseparator: - +:toc: macro +endif::[] +// URLs +:docs: link:../ +ifdef::env-github[:docs: https://asciidoctor.org/docs/] +:user: {docs}user-manual/ +ifdef::env-browser[] +:docs: link:index.adoc +:user: link:user-manual.adoc +endif::[] +:uri-fontawesome: https://fontawesome.com/v4.7.0/ +:uri-icon-in: {user}#inline-icons +:uri-icon-attrs: {user}#size-rotate-and-flip +:uri-video: {user}#video +:uri-checklist: {user}#checklist +:uri-marker: {user}#custom-markers +:uri-list-num: {user}#numbering-styles +:uri-imagesdir: {user}#setting-the-location-of-images +:uri-image-attrs: {user}#putting-images-in-their-place +:uri-toc: {user}#user-toc +:uri-para: {user}#paragraph +:uri-literal: {user}#literal-text-and-blocks +:uri-admon: {user}#admonition +:uri-bold: {user}#bold-and-italic +:uri-quote: {user}#curved +:uri-sub: {user}#subscript-and-superscript +:uri-mono: {user}#mono +:uri-css: {user}#custom-styling-with-attributes +:uri-pass: {user}#pass-macros +:uri-mailinglist: http://discuss.asciidoctor.org +:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references +:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs + +//// +Syntax to cover: +- preface +- index terms +- built-in attributes (such as {author}, {revision}, etc) +- start=n for ordered lists +- horizontal description list +- anchor for any block element +- block metadata (missing example of normal attributes) +- command line reference? perhaps another doc? yes + +PDF TODO: +- add license on title page (legalnotice tag) +- table cell bg +- show example of section levels +- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) +- style sidebar block +//// + +ifdef::basebackend-docbook[] +[preface] +== About +endif::basebackend-docbook[] + +AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. +{description} + +[NOTE] +==== +These examples focus on the output generated by the HTML backend. +AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. +==== + +toc::[] + +== Paragraphs + +.Normal +---- +include::{includedir}/ex-text.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-para] +==== + +.Literal +---- +include::{includedir}/ex-literal.adoc[tag=b-imp] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp] +==== + +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-admon.adoc[tag=b-para] +==== + +NOTE: You can also create <>. + +.Lead paragraph +---- +include::{includedir}/ex-text.adoc[tag=b-lead] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-lead] +==== + +NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. + +.More Paragraph, Admonition and Literal Block Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-para}[Paragraphs] +* {uri-literal}[Literal Text and Blocks] +* {uri-admon}[Admonitions] +**** + +== Formatted Text + +.Bold, Italic, and Monospace +---- +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +==== + +.Monospace vs codespan +---- +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +==== + +NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. +Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. +See the <> for details. + +.Marks and Custom Styling +---- +include::{includedir}/ex-text.adoc[tag=css-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=css-all] +==== + +.Superscript and Subscript +---- +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +==== + +.Curved Quotation Marks and Apostrophes (Smart Quotes) +---- +include::{includedir}/ex-text.adoc[tag=b-c-quote] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-c-quote] +==== + +.More Text Formatting Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-bold}[Bold and Italic Formatting] +* {uri-quote}[Quotation Marks and Apostrophes] +* {uri-sub}[Subscript and Superscript] +* {uri-mono}[Monospace Formatting] +* {uri-css}[Custom Styling with Attributes] +* {uri-pass}[Passthrough Macros] +**** + +== Document Header + +IMPORTANT: A header is optional. + +CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. + +.Title only +---- +include::{includedir}/ex-header-title.adoc[tag=b-base] +---- + +.Title and author line +---- +include::{includedir}/ex-author.adoc[tag=b-base] +---- + +TIP: Asciidoctor allows multiple authors in the author line. +Use the semi-colon character to separate each author. + +.Title, author line and revision line +---- +include::{includedir}/ex-rev.adoc[tag=b-base] +---- + +IMPORTANT: You cannot have a revision line without an author line. + +.Document header with attributes +---- +include::{includedir}/ex-header-attr.adoc[tag=b-base] +---- + +[#section-titles] +== Section Titles (Headings) + +.Article doctype +---- +include::{includedir}/ex-section.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-base] +==== + +WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. + +NOTE: The number of equal signs matches the heading level in the HTML output. +For example, _Section Level 1_ becomes an `

` heading. + +.Book doctype +---- +include::{includedir}/ex-section.adoc[tag=book] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-book] +==== + +//// +IMPORTANT: There are two other ways to define a section title. +_Their omission is intentional_. +They both require more markup and are therefore unnecessary. +The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. +The reader never sees the extra markup, so why type it? +*Be frugal!* +//// + +.Explicit id +---- +[#primitives-nulls] +== Primitive types and null values +---- + +.Section anchors and links (Asciidoctor only) + +`sectanchors`:: +When this document attribute is set, a section icon anchor appears in front of the section title. + +`sectlinks`:: +When this document attribute is set, the section titles become self-links. +This enables a reader to bookmark the section. + +NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. + +== Include Files + +.Document parts +---- +include::{includedir}/ex-include.adoc[tag=base] +---- + +CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. +Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. + +.Include content from a URI +---- +include::{includedir}/ex-include.adoc[tag=uri] +---- + +NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. +Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. + +== Breaks + +.Hard line break +---- +include::{includedir}/ex-text.adoc[tag=hb-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=hb-all] +==== + +.Thematic break (aka horizontal rule) +---- +include::{includedir}/ex-hr.adoc[tag=in-between] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=in-between] +==== + +.Page break +---- +<<< +---- + +== Lists + +.Unordered, basic +---- +include::{includedir}/ex-ulist.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base] +==== + +.Unordered, basic (alt) +---- +include::{includedir}/ex-ulist.adoc[tag=base-alt] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base-alt] +==== + +NOTE: A blank line is required before and after a list to separated it from other blocks. + +TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. +The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. + +.Unordered, max nesting +---- +include::{includedir}/ex-ulist.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=max] +==== + +TIP: The unordered list marker can be changed using {uri-marker}[block styles]. + +.Ordered, basic +---- +include::{includedir}/ex-o-list.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=b-base] +==== + +NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. + +.Ordered, nested +---- +include::{includedir}/ex-o-list.adoc[tag=nest] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=nest] +==== + +.Ordered, max nesting +---- +include::{includedir}/ex-o-list.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=max] +==== + +TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. + +.Checklist +---- +include::{includedir}/ex-ulist.adoc[tag=check] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=check] +==== + +TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. + +.Description, single-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base] +==== + +.Description, multi-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +==== + +.Q&A +---- +include::{includedir}/ex-dlist.adoc[tag=qa] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=qa] +==== + +.Mixed +---- +include::{includedir}/ex-dlist.adoc[tag=3-mix] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=3-mix] +==== + +TIP: Lists can be indented. +Leading whitespace is not significant. + +.Complex content in outline lists +---- +include::{includedir}/ex-ulist.adoc[tag=b-complex] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=b-complex] +==== + +== Links + +.External +---- +include::{includedir}/ex-url.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-base] +==== + +.With spaces and special characters +---- +include::{includedir}/ex-url.adoc[tag=b-spaces] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-spaces] +==== + +.Windows path +---- +include::{includedir}/ex-url.adoc[tag=b-windows] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-windows] +==== + +.Relative +---- +link:index.html[Docs] +---- + +[.result] +==== +link:index.html[Docs] +==== + +.Email and IRC +---- +include::{includedir}/ex-url.adoc[tag=b-scheme] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-scheme] +==== + +.Link with attributes (Asciidoctor only) +---- +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +==== + +NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. +To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. +Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. +When attribute parsing is enabled, you must quote the link text if it contains a comma. + +.Inline anchors +---- +include::{includedir}/ex-xref.adoc[tag=anchor] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=anchor] +==== + +.Internal cross references +---- +include::{includedir}/ex-xref.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=b-base] +==== + +.Inter-document cross references (Asciidoctor only) +---- +include::{includedir}/ex-xref.adoc[tag=b-inter] +---- + +== Images + +Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. +You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. + +The `imagesdir` attribute can be an absolute path, relative path, or base URL. +When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. + +.Block +---- +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +==== + +.Inline +---- +include::{includedir}/ex-image.adoc[tag=in] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in] +==== + +IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. +(All macros follow this pattern). +You use an inline image when you need to place the image in a line of text. +Otherwise, you should prefer the block form. + +.Inline image with positioning role +---- +include::{includedir}/ex-image.adoc[tag=in-role] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in-role] +==== + +TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. + +.Embedded +---- +include::{includedir}/ex-image.adoc[tag=data] +---- + +NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. + +TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. + +== Videos + +.Block +---- +include::{includedir}/ex-video.adoc[tag=base] + +include::{includedir}/ex-video.adoc[tag=attr] +---- + +.Embedded Youtube video +---- +include::{includedir}/ex-video.adoc[tag=you] +---- + +.Embedded Vimeo video +---- +include::{includedir}/ex-video.adoc[tag=vim] +---- + +TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. + +== Source Code + +.Inline (monospace only) +---- +include::{includedir}/ex-text.adoc[tag=b-mono-code] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-mono-code] +==== + +.Inline (literal) +---- +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +==== + +.Literal line +---- +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +==== + +.Literal block +---- +include::{includedir}/ex-literal.adoc[tag=b-block] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-block] +==== + +[listing] +.Listing block with title, no syntax highlighting +.... +include::{includedir}/ex-listing.adoc[tag=b-base] +.... + +[.result] +==== +include::{includedir}/ex-listing.adoc[tag=b-base] +==== + +[listing] +.Code block with title and syntax highlighting +.... +include::{includedir}/ex-src.adoc[tag=src-base] +.... + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-base] +==== + +[listing,subs=specialchars] +.Code block with callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-src] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-src] +==== + +[listing,subs=specialchars] +.Code block with non-selectable callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +==== + +[listing,subs=specialchars] +.XML code block with a non-selectable callout +.... +include::{includedir}/ex-callout.adoc[tag=source-xml] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=source-xml] +==== + +[listing] +.Code block sourced from file +.... +include::{includedir}/ex-src.adoc[tag=src-inc] +.... + +[listing] +.Code block sourced from file relative to source directory +.... +include::{includedir}/ex-src.adoc[tag=rel] +.... + +[listing] +.Strip leading indentation from source +.... +include::{includedir}/ex-src.adoc[tag=ind] +.... + +[NOTE] +==== +* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). +* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. +==== + +.Code block without delimiters (no blank lines) +---- +include::{includedir}/ex-src.adoc[tag=src-para] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-para] +==== + +[IMPORTANT] +.Enabling the syntax highlighter +==== +Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. + + :source-highlighter: pygments + +The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. +==== + +== More Delimited Blocks + +.Sidebar +---- +include::{includedir}/ex-sidebar.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-sidebar.adoc[tag=base] +==== + +NOTE: Any block can have a title, positioned above the block. +A block title is a line of text that starts with a dot. +The dot cannot be followed by a space. + +.Example +---- +include::{includedir}/ex-example.adoc[tag=base] +---- + +[example.result] +-- +include::{includedir}/ex-example.adoc[tag=base] +-- + +[#admon-bl] +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-bl] +---- + +[.result] +===== +include::{includedir}/ex-admon.adoc[tag=b-bl] +===== + +[TIP] +.Admonition and callout icons +==== +Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. + +To use this feature, set the value of the `icons` document attribute to `font`. +Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. + +Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. +==== + +.Blockquote +---- +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +==== + +.Abbreviated blockquote (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=abbr] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=abbr] +==== + +.Air quotes: the best thing since fenced code blocks (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=air] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=air] +==== + +.Passthrough +---- +include::{includedir}/ex-pass.adoc[tag=b-bl] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-bl] +==== + +.Open +---- +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +---- + +[.result] +==== +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +==== + +[listing] +.Custom substitutions +.... +include::{includedir}/ex-listing.adoc[tag=subs] +.... + +[.result] +==== +// the attribute value is hard-coded in this result since the example depends +// on a hypothetical document attribute +include::{includedir}/ex-listing.adoc[tag=subs-out] +==== + +== Block Id, Role and Options + +.Traditional (longhand) markup method for assigning block id and role +---- +[[goals]] +[role="incremental"] +* Goal 1 +* Goal 2 +---- + +.Shorthand markup method for assigning block id and role (Asciidoctor only) +---- +[#goals.incremental] +* Goal 1 +* Goal 2 +---- + +[TIP] +==== +* To specify multiple roles using the shorthand syntax, separate them by dots. +* The order of `id` and `role` values in the shorthand syntax does not matter. +==== + +.Traditional (longhand) markup method for assigning quoted text anchor (id) and role +---- +[[free_the_world]][big goal]_free the world_ +---- + +.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) +---- +[#free_the_world.big.goal]_free the world_ +---- + +.Role assigned to text enclosed in backticks +---- +[.rolename]`monospace text` +---- + +.Traditional (longhand) markup method for assigning block options +---- +[options="header,footer,autowidth"] +|=== +|Cell A |Cell B +|=== +---- + +.Shorthand markup method for assigning block options (Asciidoctor only) +---- +[%header%footer%autowidth] +|=== +|Cell A |Cell B +|=== +---- + +== Comments + +.Line +---- +include::{includedir}/ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::{includedir}/ex-comment.adoc[tag=bl] +---- + +== Tables + +.Table with a title, three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-base-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-base-h] +==== +<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. +<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. + +.Table with two columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-h] +==== +<1> The `+*+` in the `cols` attribute is the repeat operator. +It means repeat the column specification across the remaining of columns. +In this case, we are repeating the default formatting across 2 columns. +When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. + +.Table with three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-indv-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-indv] +==== +<1> In this example, the `cols` attribute has two functions. +It specifies that this table has three columns, and it sets their relative widths. + +.Table with column containing AsciiDoc content +---- +include::{includedir}/ex-table.adoc[tag=b-col-a] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-a] +==== + +.Table from CSV data +---- +include::{includedir}/ex-table-data.adoc[tag=csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=csv] +==== + +.Table from CSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-csv] +==== + +.Table from CSV data in file +---- +include::{includedir}/ex-table-data.adoc[tag=i-csv] +---- + +.Table from DSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +==== + +.Table with formatted, aligned and merged cells +---- +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +---- + +[.result] +==== +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +==== + +== UI Macros + +IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. + +.Keyboard shortcuts (inline kbd macro) +---- +include::{includedir}/ex-ui.adoc[tag=key] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=key] +==== + +.Menu selections (inline menu macro) +---- +include::{includedir}/ex-ui.adoc[tag=menu] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=menu] +==== + +.Buttons (inline btn macro) +---- +include::{includedir}/ex-ui.adoc[tag=button] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=button] +==== + +== Attributes and Substitutions + +.Attribute declaration and usage +---- +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +---- + +[.result] +==== +// I have to use a nested doc hack here, otherwise the attributes won't resolve +[.unstyled] +|=== +a| +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +|=== +==== + +.Attribute assignment precedence (highest to lowest) +- Attribute passed to the API or CLI that does not end in `@` +- Attribute defined in the document +- Attribute passed to the API or CLI that ends in `@` +- Intrinsic attribute value (default values) + +TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. + +// Table of predefined attributes for character replacements +include::{includedir}/attrs-charref.adoc[tag=table] + +// Table of environment attributes +include::{includedir}/attrs-env.adoc[tag=table] + +.Named substitutions +include::{includedir}/subs-apply.adoc[tag=group] + +.Counter attributes +---- +include::{includedir}/ex-counter.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-counter.adoc[tag=base] +==== + +== Text Replacement + +// Table of text replacements performed during replacements substitution +include::{includedir}/subs-symbol-repl.adoc[] + +TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. + +== Escaping Text + +.Backslash +---- +include::{includedir}/ex-subs.adoc[tag=b-slash] +---- + +[.result] +==== +include::{includedir}/ex-subs.adoc[tag=b-slash] +==== + +.Passthrough ("`plus for passthrough`") +---- +include::{includedir}/ex-pass.adoc[tag=plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=plus] +==== + +//// +.Double dollar +---- +include::{includedir}/ex-pass.adoc[tag=b-dollar] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-dollar] +==== +//// + +.Raw (triple plus and inline pass macro) +---- +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +==== + +//// +.Backticks +---- +include::{includedir}/ex-pass.adoc[tag=b-tick] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-tick] +==== +//// + +== Table of Contents (ToC) + +.Document with ToC +---- +include::{includedir}/ex-toc.adoc[tag=base] +---- + +.Document with ToC positioned on the right +---- +include::{includedir}/ex-toc.adoc[tag=pos] +---- + +TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. + +== Bibliography + +.Bibliography with inbound references +---- +include::{includedir}/ex-biblio.adoc[tag=base] +---- + +[.result] +==== +|=== +a| +include::{includedir}/ex-biblio.adoc[tag=base] +|=== +==== + +[#section-footnotes] +== Footnotes + +.Normal and reusable footnotes +---- +include::{includedir}/ex-footnote.adoc[tag=base] +---- + +[.result] +==== +[.unstyled] +|=== +a| +include::{includedir}/ex-footnote.adoc[tag=base] +|=== +==== + +[#markdown-compatibility] +== Markdown Compatibility + +Markdown compatible syntax is only available when using Asciidoctor. + +.Markdown-style headings +---- +include::{includedir}/ex-section.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-md] +==== + +.Fenced code block with syntax highlighting +---- +include::{includedir}/ex-src.adoc[tag=fence] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=fence] +==== + +.Markdown-style blockquote +---- +include::{includedir}/ex-quote.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md] +==== + +.Markdown-style blockquote with block content +---- +include::{includedir}/ex-quote.adoc[tag=md-alt] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md-alt] +==== + +.Markdown-style horizontal rules +---- +include::{includedir}/ex-hr.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=md] +==== + +== User Manual and Help + +To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. +Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. += AsciiDoc Syntax Quick Reference +Dan Allen; Sarah White +v1.0.4, 2014-08-08 +:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. +:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet +:page-description: {description} +:page-keywords: {keywords} +:page-layout: docs +:page-javascripts: [view-result] +:imagesdir: ../images +:includedir: _includes +:experimental: +:table-caption!: +:example-caption!: +:figure-caption!: +ifndef::env-site[] +:idprefix: +:idseparator: - +:toc: macro +endif::[] +// URLs +:docs: link:../ +ifdef::env-github[:docs: https://asciidoctor.org/docs/] +:user: {docs}user-manual/ +ifdef::env-browser[] +:docs: link:index.adoc +:user: link:user-manual.adoc +endif::[] +:uri-fontawesome: https://fontawesome.com/v4.7.0/ +:uri-icon-in: {user}#inline-icons +:uri-icon-attrs: {user}#size-rotate-and-flip +:uri-video: {user}#video +:uri-checklist: {user}#checklist +:uri-marker: {user}#custom-markers +:uri-list-num: {user}#numbering-styles +:uri-imagesdir: {user}#setting-the-location-of-images +:uri-image-attrs: {user}#putting-images-in-their-place +:uri-toc: {user}#user-toc +:uri-para: {user}#paragraph +:uri-literal: {user}#literal-text-and-blocks +:uri-admon: {user}#admonition +:uri-bold: {user}#bold-and-italic +:uri-quote: {user}#curved +:uri-sub: {user}#subscript-and-superscript +:uri-mono: {user}#mono +:uri-css: {user}#custom-styling-with-attributes +:uri-pass: {user}#pass-macros +:uri-mailinglist: http://discuss.asciidoctor.org +:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references +:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs + +//// +Syntax to cover: +- preface +- index terms +- built-in attributes (such as {author}, {revision}, etc) +- start=n for ordered lists +- horizontal description list +- anchor for any block element +- block metadata (missing example of normal attributes) +- command line reference? perhaps another doc? yes + +PDF TODO: +- add license on title page (legalnotice tag) +- table cell bg +- show example of section levels +- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) +- style sidebar block +//// + +ifdef::basebackend-docbook[] +[preface] +== About +endif::basebackend-docbook[] + +AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. +{description} + +[NOTE] +==== +These examples focus on the output generated by the HTML backend. +AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. +==== + +toc::[] + +== Paragraphs + +.Normal +---- +include::{includedir}/ex-text.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-para] +==== + +.Literal +---- +include::{includedir}/ex-literal.adoc[tag=b-imp] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp] +==== + +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-admon.adoc[tag=b-para] +==== + +NOTE: You can also create <>. + +.Lead paragraph +---- +include::{includedir}/ex-text.adoc[tag=b-lead] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-lead] +==== + +NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. + +.More Paragraph, Admonition and Literal Block Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-para}[Paragraphs] +* {uri-literal}[Literal Text and Blocks] +* {uri-admon}[Admonitions] +**** + +== Formatted Text + +.Bold, Italic, and Monospace +---- +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +==== + +.Monospace vs codespan +---- +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +==== + +NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. +Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. +See the <> for details. + +.Marks and Custom Styling +---- +include::{includedir}/ex-text.adoc[tag=css-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=css-all] +==== + +.Superscript and Subscript +---- +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +==== + +.Curved Quotation Marks and Apostrophes (Smart Quotes) +---- +include::{includedir}/ex-text.adoc[tag=b-c-quote] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-c-quote] +==== + +.More Text Formatting Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-bold}[Bold and Italic Formatting] +* {uri-quote}[Quotation Marks and Apostrophes] +* {uri-sub}[Subscript and Superscript] +* {uri-mono}[Monospace Formatting] +* {uri-css}[Custom Styling with Attributes] +* {uri-pass}[Passthrough Macros] +**** + +== Document Header + +IMPORTANT: A header is optional. + +CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. + +.Title only +---- +include::{includedir}/ex-header-title.adoc[tag=b-base] +---- + +.Title and author line +---- +include::{includedir}/ex-author.adoc[tag=b-base] +---- + +TIP: Asciidoctor allows multiple authors in the author line. +Use the semi-colon character to separate each author. + +.Title, author line and revision line +---- +include::{includedir}/ex-rev.adoc[tag=b-base] +---- + +IMPORTANT: You cannot have a revision line without an author line. + +.Document header with attributes +---- +include::{includedir}/ex-header-attr.adoc[tag=b-base] +---- + +[#section-titles] +== Section Titles (Headings) + +.Article doctype +---- +include::{includedir}/ex-section.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-base] +==== + +WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. + +NOTE: The number of equal signs matches the heading level in the HTML output. +For example, _Section Level 1_ becomes an `

` heading. + +.Book doctype +---- +include::{includedir}/ex-section.adoc[tag=book] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-book] +==== + +//// +IMPORTANT: There are two other ways to define a section title. +_Their omission is intentional_. +They both require more markup and are therefore unnecessary. +The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. +The reader never sees the extra markup, so why type it? +*Be frugal!* +//// + +.Explicit id +---- +[#primitives-nulls] +== Primitive types and null values +---- + +.Section anchors and links (Asciidoctor only) + +`sectanchors`:: +When this document attribute is set, a section icon anchor appears in front of the section title. + +`sectlinks`:: +When this document attribute is set, the section titles become self-links. +This enables a reader to bookmark the section. + +NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. + +== Include Files + +.Document parts +---- +include::{includedir}/ex-include.adoc[tag=base] +---- + +CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. +Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. + +.Include content from a URI +---- +include::{includedir}/ex-include.adoc[tag=uri] +---- + +NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. +Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. + +== Breaks + +.Hard line break +---- +include::{includedir}/ex-text.adoc[tag=hb-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=hb-all] +==== + +.Thematic break (aka horizontal rule) +---- +include::{includedir}/ex-hr.adoc[tag=in-between] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=in-between] +==== + +.Page break +---- +<<< +---- + +== Lists + +.Unordered, basic +---- +include::{includedir}/ex-ulist.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base] +==== + +.Unordered, basic (alt) +---- +include::{includedir}/ex-ulist.adoc[tag=base-alt] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base-alt] +==== + +NOTE: A blank line is required before and after a list to separated it from other blocks. + +TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. +The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. + +.Unordered, max nesting +---- +include::{includedir}/ex-ulist.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=max] +==== + +TIP: The unordered list marker can be changed using {uri-marker}[block styles]. + +.Ordered, basic +---- +include::{includedir}/ex-o-list.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=b-base] +==== + +NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. + +.Ordered, nested +---- +include::{includedir}/ex-o-list.adoc[tag=nest] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=nest] +==== + +.Ordered, max nesting +---- +include::{includedir}/ex-o-list.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=max] +==== + +TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. + +.Checklist +---- +include::{includedir}/ex-ulist.adoc[tag=check] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=check] +==== + +TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. + +.Description, single-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base] +==== + +.Description, multi-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +==== + +.Q&A +---- +include::{includedir}/ex-dlist.adoc[tag=qa] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=qa] +==== + +.Mixed +---- +include::{includedir}/ex-dlist.adoc[tag=3-mix] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=3-mix] +==== + +TIP: Lists can be indented. +Leading whitespace is not significant. + +.Complex content in outline lists +---- +include::{includedir}/ex-ulist.adoc[tag=b-complex] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=b-complex] +==== + +== Links + +.External +---- +include::{includedir}/ex-url.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-base] +==== + +.With spaces and special characters +---- +include::{includedir}/ex-url.adoc[tag=b-spaces] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-spaces] +==== + +.Windows path +---- +include::{includedir}/ex-url.adoc[tag=b-windows] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-windows] +==== + +.Relative +---- +link:index.html[Docs] +---- + +[.result] +==== +link:index.html[Docs] +==== + +.Email and IRC +---- +include::{includedir}/ex-url.adoc[tag=b-scheme] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-scheme] +==== + +.Link with attributes (Asciidoctor only) +---- +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +==== + +NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. +To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. +Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. +When attribute parsing is enabled, you must quote the link text if it contains a comma. + +.Inline anchors +---- +include::{includedir}/ex-xref.adoc[tag=anchor] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=anchor] +==== + +.Internal cross references +---- +include::{includedir}/ex-xref.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=b-base] +==== + +.Inter-document cross references (Asciidoctor only) +---- +include::{includedir}/ex-xref.adoc[tag=b-inter] +---- + +== Images + +Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. +You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. + +The `imagesdir` attribute can be an absolute path, relative path, or base URL. +When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. + +.Block +---- +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +==== + +.Inline +---- +include::{includedir}/ex-image.adoc[tag=in] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in] +==== + +IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. +(All macros follow this pattern). +You use an inline image when you need to place the image in a line of text. +Otherwise, you should prefer the block form. + +.Inline image with positioning role +---- +include::{includedir}/ex-image.adoc[tag=in-role] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in-role] +==== + +TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. + +.Embedded +---- +include::{includedir}/ex-image.adoc[tag=data] +---- + +NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. + +TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. + +== Videos + +.Block +---- +include::{includedir}/ex-video.adoc[tag=base] + +include::{includedir}/ex-video.adoc[tag=attr] +---- + +.Embedded Youtube video +---- +include::{includedir}/ex-video.adoc[tag=you] +---- + +.Embedded Vimeo video +---- +include::{includedir}/ex-video.adoc[tag=vim] +---- + +TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. + +== Source Code + +.Inline (monospace only) +---- +include::{includedir}/ex-text.adoc[tag=b-mono-code] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-mono-code] +==== + +.Inline (literal) +---- +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +==== + +.Literal line +---- +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +==== + +.Literal block +---- +include::{includedir}/ex-literal.adoc[tag=b-block] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-block] +==== + +[listing] +.Listing block with title, no syntax highlighting +.... +include::{includedir}/ex-listing.adoc[tag=b-base] +.... + +[.result] +==== +include::{includedir}/ex-listing.adoc[tag=b-base] +==== + +[listing] +.Code block with title and syntax highlighting +.... +include::{includedir}/ex-src.adoc[tag=src-base] +.... + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-base] +==== + +[listing,subs=specialchars] +.Code block with callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-src] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-src] +==== + +[listing,subs=specialchars] +.Code block with non-selectable callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +==== + +[listing,subs=specialchars] +.XML code block with a non-selectable callout +.... +include::{includedir}/ex-callout.adoc[tag=source-xml] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=source-xml] +==== + +[listing] +.Code block sourced from file +.... +include::{includedir}/ex-src.adoc[tag=src-inc] +.... + +[listing] +.Code block sourced from file relative to source directory +.... +include::{includedir}/ex-src.adoc[tag=rel] +.... + +[listing] +.Strip leading indentation from source +.... +include::{includedir}/ex-src.adoc[tag=ind] +.... + +[NOTE] +==== +* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). +* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. +==== + +.Code block without delimiters (no blank lines) +---- +include::{includedir}/ex-src.adoc[tag=src-para] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-para] +==== + +[IMPORTANT] +.Enabling the syntax highlighter +==== +Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. + + :source-highlighter: pygments + +The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. +==== + +== More Delimited Blocks + +.Sidebar +---- +include::{includedir}/ex-sidebar.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-sidebar.adoc[tag=base] +==== + +NOTE: Any block can have a title, positioned above the block. +A block title is a line of text that starts with a dot. +The dot cannot be followed by a space. + +.Example +---- +include::{includedir}/ex-example.adoc[tag=base] +---- + +[example.result] +-- +include::{includedir}/ex-example.adoc[tag=base] +-- + +[#admon-bl] +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-bl] +---- + +[.result] +===== +include::{includedir}/ex-admon.adoc[tag=b-bl] +===== + +[TIP] +.Admonition and callout icons +==== +Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. + +To use this feature, set the value of the `icons` document attribute to `font`. +Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. + +Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. +==== + +.Blockquote +---- +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +==== + +.Abbreviated blockquote (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=abbr] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=abbr] +==== + +.Air quotes: the best thing since fenced code blocks (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=air] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=air] +==== + +.Passthrough +---- +include::{includedir}/ex-pass.adoc[tag=b-bl] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-bl] +==== + +.Open +---- +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +---- + +[.result] +==== +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +==== + +[listing] +.Custom substitutions +.... +include::{includedir}/ex-listing.adoc[tag=subs] +.... + +[.result] +==== +// the attribute value is hard-coded in this result since the example depends +// on a hypothetical document attribute +include::{includedir}/ex-listing.adoc[tag=subs-out] +==== + +== Block Id, Role and Options + +.Traditional (longhand) markup method for assigning block id and role +---- +[[goals]] +[role="incremental"] +* Goal 1 +* Goal 2 +---- + +.Shorthand markup method for assigning block id and role (Asciidoctor only) +---- +[#goals.incremental] +* Goal 1 +* Goal 2 +---- + +[TIP] +==== +* To specify multiple roles using the shorthand syntax, separate them by dots. +* The order of `id` and `role` values in the shorthand syntax does not matter. +==== + +.Traditional (longhand) markup method for assigning quoted text anchor (id) and role +---- +[[free_the_world]][big goal]_free the world_ +---- + +.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) +---- +[#free_the_world.big.goal]_free the world_ +---- + +.Role assigned to text enclosed in backticks +---- +[.rolename]`monospace text` +---- + +.Traditional (longhand) markup method for assigning block options +---- +[options="header,footer,autowidth"] +|=== +|Cell A |Cell B +|=== +---- + +.Shorthand markup method for assigning block options (Asciidoctor only) +---- +[%header%footer%autowidth] +|=== +|Cell A |Cell B +|=== +---- + +== Comments + +.Line +---- +include::{includedir}/ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::{includedir}/ex-comment.adoc[tag=bl] +---- + +== Tables + +.Table with a title, three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-base-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-base-h] +==== +<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. +<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. + +.Table with two columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-h] +==== +<1> The `+*+` in the `cols` attribute is the repeat operator. +It means repeat the column specification across the remaining of columns. +In this case, we are repeating the default formatting across 2 columns. +When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. + +.Table with three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-indv-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-indv] +==== +<1> In this example, the `cols` attribute has two functions. +It specifies that this table has three columns, and it sets their relative widths. + +.Table with column containing AsciiDoc content +---- +include::{includedir}/ex-table.adoc[tag=b-col-a] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-a] +==== + +.Table from CSV data +---- +include::{includedir}/ex-table-data.adoc[tag=csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=csv] +==== + +.Table from CSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-csv] +==== + +.Table from CSV data in file +---- +include::{includedir}/ex-table-data.adoc[tag=i-csv] +---- + +.Table from DSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +==== + +.Table with formatted, aligned and merged cells +---- +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +---- + +[.result] +==== +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +==== + +== UI Macros + +IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. + +.Keyboard shortcuts (inline kbd macro) +---- +include::{includedir}/ex-ui.adoc[tag=key] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=key] +==== + +.Menu selections (inline menu macro) +---- +include::{includedir}/ex-ui.adoc[tag=menu] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=menu] +==== + +.Buttons (inline btn macro) +---- +include::{includedir}/ex-ui.adoc[tag=button] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=button] +==== + +== Attributes and Substitutions + +.Attribute declaration and usage +---- +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +---- + +[.result] +==== +// I have to use a nested doc hack here, otherwise the attributes won't resolve +[.unstyled] +|=== +a| +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +|=== +==== + +.Attribute assignment precedence (highest to lowest) +- Attribute passed to the API or CLI that does not end in `@` +- Attribute defined in the document +- Attribute passed to the API or CLI that ends in `@` +- Intrinsic attribute value (default values) + +TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. + +// Table of predefined attributes for character replacements +include::{includedir}/attrs-charref.adoc[tag=table] + +// Table of environment attributes +include::{includedir}/attrs-env.adoc[tag=table] + +.Named substitutions +include::{includedir}/subs-apply.adoc[tag=group] + +.Counter attributes +---- +include::{includedir}/ex-counter.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-counter.adoc[tag=base] +==== + +== Text Replacement + +// Table of text replacements performed during replacements substitution +include::{includedir}/subs-symbol-repl.adoc[] + +TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. + +== Escaping Text + +.Backslash +---- +include::{includedir}/ex-subs.adoc[tag=b-slash] +---- + +[.result] +==== +include::{includedir}/ex-subs.adoc[tag=b-slash] +==== + +.Passthrough ("`plus for passthrough`") +---- +include::{includedir}/ex-pass.adoc[tag=plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=plus] +==== + +//// +.Double dollar +---- +include::{includedir}/ex-pass.adoc[tag=b-dollar] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-dollar] +==== +//// + +.Raw (triple plus and inline pass macro) +---- +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +==== + +//// +.Backticks +---- +include::{includedir}/ex-pass.adoc[tag=b-tick] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-tick] +==== +//// + +== Table of Contents (ToC) + +.Document with ToC +---- +include::{includedir}/ex-toc.adoc[tag=base] +---- + +.Document with ToC positioned on the right +---- +include::{includedir}/ex-toc.adoc[tag=pos] +---- + +TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. + +== Bibliography + +.Bibliography with inbound references +---- +include::{includedir}/ex-biblio.adoc[tag=base] +---- + +[.result] +==== +|=== +a| +include::{includedir}/ex-biblio.adoc[tag=base] +|=== +==== + +[#section-footnotes] +== Footnotes + +.Normal and reusable footnotes +---- +include::{includedir}/ex-footnote.adoc[tag=base] +---- + +[.result] +==== +[.unstyled] +|=== +a| +include::{includedir}/ex-footnote.adoc[tag=base] +|=== +==== + +[#markdown-compatibility] +== Markdown Compatibility + +Markdown compatible syntax is only available when using Asciidoctor. + +.Markdown-style headings +---- +include::{includedir}/ex-section.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-md] +==== + +.Fenced code block with syntax highlighting +---- +include::{includedir}/ex-src.adoc[tag=fence] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=fence] +==== + +.Markdown-style blockquote +---- +include::{includedir}/ex-quote.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md] +==== + +.Markdown-style blockquote with block content +---- +include::{includedir}/ex-quote.adoc[tag=md-alt] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md-alt] +==== + +.Markdown-style horizontal rules +---- +include::{includedir}/ex-hr.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=md] +==== + +== User Manual and Help + +To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. +Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. += AsciiDoc Syntax Quick Reference +Dan Allen; Sarah White +v1.0.4, 2014-08-08 +:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. +:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet +:page-description: {description} +:page-keywords: {keywords} +:page-layout: docs +:page-javascripts: [view-result] +:imagesdir: ../images +:includedir: _includes +:experimental: +:table-caption!: +:example-caption!: +:figure-caption!: +ifndef::env-site[] +:idprefix: +:idseparator: - +:toc: macro +endif::[] +// URLs +:docs: link:../ +ifdef::env-github[:docs: https://asciidoctor.org/docs/] +:user: {docs}user-manual/ +ifdef::env-browser[] +:docs: link:index.adoc +:user: link:user-manual.adoc +endif::[] +:uri-fontawesome: https://fontawesome.com/v4.7.0/ +:uri-icon-in: {user}#inline-icons +:uri-icon-attrs: {user}#size-rotate-and-flip +:uri-video: {user}#video +:uri-checklist: {user}#checklist +:uri-marker: {user}#custom-markers +:uri-list-num: {user}#numbering-styles +:uri-imagesdir: {user}#setting-the-location-of-images +:uri-image-attrs: {user}#putting-images-in-their-place +:uri-toc: {user}#user-toc +:uri-para: {user}#paragraph +:uri-literal: {user}#literal-text-and-blocks +:uri-admon: {user}#admonition +:uri-bold: {user}#bold-and-italic +:uri-quote: {user}#curved +:uri-sub: {user}#subscript-and-superscript +:uri-mono: {user}#mono +:uri-css: {user}#custom-styling-with-attributes +:uri-pass: {user}#pass-macros +:uri-mailinglist: http://discuss.asciidoctor.org +:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references +:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs + +//// +Syntax to cover: +- preface +- index terms +- built-in attributes (such as {author}, {revision}, etc) +- start=n for ordered lists +- horizontal description list +- anchor for any block element +- block metadata (missing example of normal attributes) +- command line reference? perhaps another doc? yes + +PDF TODO: +- add license on title page (legalnotice tag) +- table cell bg +- show example of section levels +- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) +- style sidebar block +//// + +ifdef::basebackend-docbook[] +[preface] +== About +endif::basebackend-docbook[] + +AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. +{description} + +[NOTE] +==== +These examples focus on the output generated by the HTML backend. +AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. +==== + +toc::[] + +== Paragraphs + +.Normal +---- +include::{includedir}/ex-text.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-para] +==== + +.Literal +---- +include::{includedir}/ex-literal.adoc[tag=b-imp] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp] +==== + +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-admon.adoc[tag=b-para] +==== + +NOTE: You can also create <>. + +.Lead paragraph +---- +include::{includedir}/ex-text.adoc[tag=b-lead] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-lead] +==== + +NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. + +.More Paragraph, Admonition and Literal Block Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-para}[Paragraphs] +* {uri-literal}[Literal Text and Blocks] +* {uri-admon}[Admonitions] +**** + +== Formatted Text + +.Bold, Italic, and Monospace +---- +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +==== + +.Monospace vs codespan +---- +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +==== + +NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. +Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. +See the <> for details. + +.Marks and Custom Styling +---- +include::{includedir}/ex-text.adoc[tag=css-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=css-all] +==== + +.Superscript and Subscript +---- +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +==== + +.Curved Quotation Marks and Apostrophes (Smart Quotes) +---- +include::{includedir}/ex-text.adoc[tag=b-c-quote] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-c-quote] +==== + +.More Text Formatting Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-bold}[Bold and Italic Formatting] +* {uri-quote}[Quotation Marks and Apostrophes] +* {uri-sub}[Subscript and Superscript] +* {uri-mono}[Monospace Formatting] +* {uri-css}[Custom Styling with Attributes] +* {uri-pass}[Passthrough Macros] +**** + +== Document Header + +IMPORTANT: A header is optional. + +CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. + +.Title only +---- +include::{includedir}/ex-header-title.adoc[tag=b-base] +---- + +.Title and author line +---- +include::{includedir}/ex-author.adoc[tag=b-base] +---- + +TIP: Asciidoctor allows multiple authors in the author line. +Use the semi-colon character to separate each author. + +.Title, author line and revision line +---- +include::{includedir}/ex-rev.adoc[tag=b-base] +---- + +IMPORTANT: You cannot have a revision line without an author line. + +.Document header with attributes +---- +include::{includedir}/ex-header-attr.adoc[tag=b-base] +---- + +[#section-titles] +== Section Titles (Headings) + +.Article doctype +---- +include::{includedir}/ex-section.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-base] +==== + +WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. + +NOTE: The number of equal signs matches the heading level in the HTML output. +For example, _Section Level 1_ becomes an `

` heading. + +.Book doctype +---- +include::{includedir}/ex-section.adoc[tag=book] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-book] +==== + +//// +IMPORTANT: There are two other ways to define a section title. +_Their omission is intentional_. +They both require more markup and are therefore unnecessary. +The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. +The reader never sees the extra markup, so why type it? +*Be frugal!* +//// + +.Explicit id +---- +[#primitives-nulls] +== Primitive types and null values +---- + +.Section anchors and links (Asciidoctor only) + +`sectanchors`:: +When this document attribute is set, a section icon anchor appears in front of the section title. + +`sectlinks`:: +When this document attribute is set, the section titles become self-links. +This enables a reader to bookmark the section. + +NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. + +== Include Files + +.Document parts +---- +include::{includedir}/ex-include.adoc[tag=base] +---- + +CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. +Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. + +.Include content from a URI +---- +include::{includedir}/ex-include.adoc[tag=uri] +---- + +NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. +Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. + +== Breaks + +.Hard line break +---- +include::{includedir}/ex-text.adoc[tag=hb-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=hb-all] +==== + +.Thematic break (aka horizontal rule) +---- +include::{includedir}/ex-hr.adoc[tag=in-between] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=in-between] +==== + +.Page break +---- +<<< +---- + +== Lists + +.Unordered, basic +---- +include::{includedir}/ex-ulist.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base] +==== + +.Unordered, basic (alt) +---- +include::{includedir}/ex-ulist.adoc[tag=base-alt] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base-alt] +==== + +NOTE: A blank line is required before and after a list to separated it from other blocks. + +TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. +The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. + +.Unordered, max nesting +---- +include::{includedir}/ex-ulist.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=max] +==== + +TIP: The unordered list marker can be changed using {uri-marker}[block styles]. + +.Ordered, basic +---- +include::{includedir}/ex-o-list.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=b-base] +==== + +NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. + +.Ordered, nested +---- +include::{includedir}/ex-o-list.adoc[tag=nest] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=nest] +==== + +.Ordered, max nesting +---- +include::{includedir}/ex-o-list.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=max] +==== + +TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. + +.Checklist +---- +include::{includedir}/ex-ulist.adoc[tag=check] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=check] +==== + +TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. + +.Description, single-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base] +==== + +.Description, multi-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +==== + +.Q&A +---- +include::{includedir}/ex-dlist.adoc[tag=qa] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=qa] +==== + +.Mixed +---- +include::{includedir}/ex-dlist.adoc[tag=3-mix] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=3-mix] +==== + +TIP: Lists can be indented. +Leading whitespace is not significant. + +.Complex content in outline lists +---- +include::{includedir}/ex-ulist.adoc[tag=b-complex] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=b-complex] +==== + +== Links + +.External +---- +include::{includedir}/ex-url.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-base] +==== + +.With spaces and special characters +---- +include::{includedir}/ex-url.adoc[tag=b-spaces] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-spaces] +==== + +.Windows path +---- +include::{includedir}/ex-url.adoc[tag=b-windows] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-windows] +==== + +.Relative +---- +link:index.html[Docs] +---- + +[.result] +==== +link:index.html[Docs] +==== + +.Email and IRC +---- +include::{includedir}/ex-url.adoc[tag=b-scheme] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-scheme] +==== + +.Link with attributes (Asciidoctor only) +---- +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +==== + +NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. +To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. +Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. +When attribute parsing is enabled, you must quote the link text if it contains a comma. + +.Inline anchors +---- +include::{includedir}/ex-xref.adoc[tag=anchor] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=anchor] +==== + +.Internal cross references +---- +include::{includedir}/ex-xref.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=b-base] +==== + +.Inter-document cross references (Asciidoctor only) +---- +include::{includedir}/ex-xref.adoc[tag=b-inter] +---- + +== Images + +Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. +You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. + +The `imagesdir` attribute can be an absolute path, relative path, or base URL. +When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. + +.Block +---- +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +==== + +.Inline +---- +include::{includedir}/ex-image.adoc[tag=in] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in] +==== + +IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. +(All macros follow this pattern). +You use an inline image when you need to place the image in a line of text. +Otherwise, you should prefer the block form. + +.Inline image with positioning role +---- +include::{includedir}/ex-image.adoc[tag=in-role] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in-role] +==== + +TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. + +.Embedded +---- +include::{includedir}/ex-image.adoc[tag=data] +---- + +NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. + +TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. + +== Videos + +.Block +---- +include::{includedir}/ex-video.adoc[tag=base] + +include::{includedir}/ex-video.adoc[tag=attr] +---- + +.Embedded Youtube video +---- +include::{includedir}/ex-video.adoc[tag=you] +---- + +.Embedded Vimeo video +---- +include::{includedir}/ex-video.adoc[tag=vim] +---- + +TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. + +== Source Code + +.Inline (monospace only) +---- +include::{includedir}/ex-text.adoc[tag=b-mono-code] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-mono-code] +==== + +.Inline (literal) +---- +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +==== + +.Literal line +---- +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +==== + +.Literal block +---- +include::{includedir}/ex-literal.adoc[tag=b-block] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-block] +==== + +[listing] +.Listing block with title, no syntax highlighting +.... +include::{includedir}/ex-listing.adoc[tag=b-base] +.... + +[.result] +==== +include::{includedir}/ex-listing.adoc[tag=b-base] +==== + +[listing] +.Code block with title and syntax highlighting +.... +include::{includedir}/ex-src.adoc[tag=src-base] +.... + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-base] +==== + +[listing,subs=specialchars] +.Code block with callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-src] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-src] +==== + +[listing,subs=specialchars] +.Code block with non-selectable callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +==== + +[listing,subs=specialchars] +.XML code block with a non-selectable callout +.... +include::{includedir}/ex-callout.adoc[tag=source-xml] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=source-xml] +==== + +[listing] +.Code block sourced from file +.... +include::{includedir}/ex-src.adoc[tag=src-inc] +.... + +[listing] +.Code block sourced from file relative to source directory +.... +include::{includedir}/ex-src.adoc[tag=rel] +.... + +[listing] +.Strip leading indentation from source +.... +include::{includedir}/ex-src.adoc[tag=ind] +.... + +[NOTE] +==== +* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). +* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. +==== + +.Code block without delimiters (no blank lines) +---- +include::{includedir}/ex-src.adoc[tag=src-para] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-para] +==== + +[IMPORTANT] +.Enabling the syntax highlighter +==== +Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. + + :source-highlighter: pygments + +The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. +==== + +== More Delimited Blocks + +.Sidebar +---- +include::{includedir}/ex-sidebar.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-sidebar.adoc[tag=base] +==== + +NOTE: Any block can have a title, positioned above the block. +A block title is a line of text that starts with a dot. +The dot cannot be followed by a space. + +.Example +---- +include::{includedir}/ex-example.adoc[tag=base] +---- + +[example.result] +-- +include::{includedir}/ex-example.adoc[tag=base] +-- + +[#admon-bl] +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-bl] +---- + +[.result] +===== +include::{includedir}/ex-admon.adoc[tag=b-bl] +===== + +[TIP] +.Admonition and callout icons +==== +Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. + +To use this feature, set the value of the `icons` document attribute to `font`. +Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. + +Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. +==== + +.Blockquote +---- +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +==== + +.Abbreviated blockquote (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=abbr] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=abbr] +==== + +.Air quotes: the best thing since fenced code blocks (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=air] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=air] +==== + +.Passthrough +---- +include::{includedir}/ex-pass.adoc[tag=b-bl] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-bl] +==== + +.Open +---- +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +---- + +[.result] +==== +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +==== + +[listing] +.Custom substitutions +.... +include::{includedir}/ex-listing.adoc[tag=subs] +.... + +[.result] +==== +// the attribute value is hard-coded in this result since the example depends +// on a hypothetical document attribute +include::{includedir}/ex-listing.adoc[tag=subs-out] +==== + +== Block Id, Role and Options + +.Traditional (longhand) markup method for assigning block id and role +---- +[[goals]] +[role="incremental"] +* Goal 1 +* Goal 2 +---- + +.Shorthand markup method for assigning block id and role (Asciidoctor only) +---- +[#goals.incremental] +* Goal 1 +* Goal 2 +---- + +[TIP] +==== +* To specify multiple roles using the shorthand syntax, separate them by dots. +* The order of `id` and `role` values in the shorthand syntax does not matter. +==== + +.Traditional (longhand) markup method for assigning quoted text anchor (id) and role +---- +[[free_the_world]][big goal]_free the world_ +---- + +.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) +---- +[#free_the_world.big.goal]_free the world_ +---- + +.Role assigned to text enclosed in backticks +---- +[.rolename]`monospace text` +---- + +.Traditional (longhand) markup method for assigning block options +---- +[options="header,footer,autowidth"] +|=== +|Cell A |Cell B +|=== +---- + +.Shorthand markup method for assigning block options (Asciidoctor only) +---- +[%header%footer%autowidth] +|=== +|Cell A |Cell B +|=== +---- + +== Comments + +.Line +---- +include::{includedir}/ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::{includedir}/ex-comment.adoc[tag=bl] +---- + +== Tables + +.Table with a title, three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-base-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-base-h] +==== +<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. +<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. + +.Table with two columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-h] +==== +<1> The `+*+` in the `cols` attribute is the repeat operator. +It means repeat the column specification across the remaining of columns. +In this case, we are repeating the default formatting across 2 columns. +When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. + +.Table with three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-indv-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-indv] +==== +<1> In this example, the `cols` attribute has two functions. +It specifies that this table has three columns, and it sets their relative widths. + +.Table with column containing AsciiDoc content +---- +include::{includedir}/ex-table.adoc[tag=b-col-a] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-a] +==== + +.Table from CSV data +---- +include::{includedir}/ex-table-data.adoc[tag=csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=csv] +==== + +.Table from CSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-csv] +==== + +.Table from CSV data in file +---- +include::{includedir}/ex-table-data.adoc[tag=i-csv] +---- + +.Table from DSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +==== + +.Table with formatted, aligned and merged cells +---- +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +---- + +[.result] +==== +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +==== + +== UI Macros + +IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. + +.Keyboard shortcuts (inline kbd macro) +---- +include::{includedir}/ex-ui.adoc[tag=key] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=key] +==== + +.Menu selections (inline menu macro) +---- +include::{includedir}/ex-ui.adoc[tag=menu] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=menu] +==== + +.Buttons (inline btn macro) +---- +include::{includedir}/ex-ui.adoc[tag=button] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=button] +==== + +== Attributes and Substitutions + +.Attribute declaration and usage +---- +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +---- + +[.result] +==== +// I have to use a nested doc hack here, otherwise the attributes won't resolve +[.unstyled] +|=== +a| +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +|=== +==== + +.Attribute assignment precedence (highest to lowest) +- Attribute passed to the API or CLI that does not end in `@` +- Attribute defined in the document +- Attribute passed to the API or CLI that ends in `@` +- Intrinsic attribute value (default values) + +TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. + +// Table of predefined attributes for character replacements +include::{includedir}/attrs-charref.adoc[tag=table] + +// Table of environment attributes +include::{includedir}/attrs-env.adoc[tag=table] + +.Named substitutions +include::{includedir}/subs-apply.adoc[tag=group] + +.Counter attributes +---- +include::{includedir}/ex-counter.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-counter.adoc[tag=base] +==== + +== Text Replacement + +// Table of text replacements performed during replacements substitution +include::{includedir}/subs-symbol-repl.adoc[] + +TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. + +== Escaping Text + +.Backslash +---- +include::{includedir}/ex-subs.adoc[tag=b-slash] +---- + +[.result] +==== +include::{includedir}/ex-subs.adoc[tag=b-slash] +==== + +.Passthrough ("`plus for passthrough`") +---- +include::{includedir}/ex-pass.adoc[tag=plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=plus] +==== + +//// +.Double dollar +---- +include::{includedir}/ex-pass.adoc[tag=b-dollar] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-dollar] +==== +//// + +.Raw (triple plus and inline pass macro) +---- +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +==== + +//// +.Backticks +---- +include::{includedir}/ex-pass.adoc[tag=b-tick] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-tick] +==== +//// + +== Table of Contents (ToC) + +.Document with ToC +---- +include::{includedir}/ex-toc.adoc[tag=base] +---- + +.Document with ToC positioned on the right +---- +include::{includedir}/ex-toc.adoc[tag=pos] +---- + +TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. + +== Bibliography + +.Bibliography with inbound references +---- +include::{includedir}/ex-biblio.adoc[tag=base] +---- + +[.result] +==== +|=== +a| +include::{includedir}/ex-biblio.adoc[tag=base] +|=== +==== + +[#section-footnotes] +== Footnotes + +.Normal and reusable footnotes +---- +include::{includedir}/ex-footnote.adoc[tag=base] +---- + +[.result] +==== +[.unstyled] +|=== +a| +include::{includedir}/ex-footnote.adoc[tag=base] +|=== +==== + +[#markdown-compatibility] +== Markdown Compatibility + +Markdown compatible syntax is only available when using Asciidoctor. + +.Markdown-style headings +---- +include::{includedir}/ex-section.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-md] +==== + +.Fenced code block with syntax highlighting +---- +include::{includedir}/ex-src.adoc[tag=fence] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=fence] +==== + +.Markdown-style blockquote +---- +include::{includedir}/ex-quote.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md] +==== + +.Markdown-style blockquote with block content +---- +include::{includedir}/ex-quote.adoc[tag=md-alt] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md-alt] +==== + +.Markdown-style horizontal rules +---- +include::{includedir}/ex-hr.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=md] +==== + +== User Manual and Help + +To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. +Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. += AsciiDoc Syntax Quick Reference +Dan Allen; Sarah White +v1.0.4, 2014-08-08 +:description: This guide is a quick reference for the common AsciiDoc document and text formatting markup. +:keywords: AsciiDoc, Asciidoctor, syntax, reference, cheatsheet +:page-description: {description} +:page-keywords: {keywords} +:page-layout: docs +:page-javascripts: [view-result] +:imagesdir: ../images +:includedir: _includes +:experimental: +:table-caption!: +:example-caption!: +:figure-caption!: +ifndef::env-site[] +:idprefix: +:idseparator: - +:toc: macro +endif::[] +// URLs +:docs: link:../ +ifdef::env-github[:docs: https://asciidoctor.org/docs/] +:user: {docs}user-manual/ +ifdef::env-browser[] +:docs: link:index.adoc +:user: link:user-manual.adoc +endif::[] +:uri-fontawesome: https://fontawesome.com/v4.7.0/ +:uri-icon-in: {user}#inline-icons +:uri-icon-attrs: {user}#size-rotate-and-flip +:uri-video: {user}#video +:uri-checklist: {user}#checklist +:uri-marker: {user}#custom-markers +:uri-list-num: {user}#numbering-styles +:uri-imagesdir: {user}#setting-the-location-of-images +:uri-image-attrs: {user}#putting-images-in-their-place +:uri-toc: {user}#user-toc +:uri-para: {user}#paragraph +:uri-literal: {user}#literal-text-and-blocks +:uri-admon: {user}#admonition +:uri-bold: {user}#bold-and-italic +:uri-quote: {user}#curved +:uri-sub: {user}#subscript-and-superscript +:uri-mono: {user}#mono +:uri-css: {user}#custom-styling-with-attributes +:uri-pass: {user}#pass-macros +:uri-mailinglist: http://discuss.asciidoctor.org +:uri-char-xml: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references +:uri-data-uri: https://developer.mozilla.org/en-US/docs/data_URIs + +//// +Syntax to cover: +- preface +- index terms +- built-in attributes (such as {author}, {revision}, etc) +- start=n for ordered lists +- horizontal description list +- anchor for any block element +- block metadata (missing example of normal attributes) +- command line reference? perhaps another doc? yes + +PDF TODO: +- add license on title page (legalnotice tag) +- table cell bg +- show example of section levels +- syntax highlight ruby code (requires switch to https://code.google.com/p/java-syntax-highlighter) +- style sidebar block +//// + +ifdef::basebackend-docbook[] +[preface] +== About +endif::basebackend-docbook[] + +AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. +{description} + +[NOTE] +==== +These examples focus on the output generated by the HTML backend. +AsciiDoc produces complementary output when generating PDF, EPUB, and DocBook. +==== + +toc::[] + +== Paragraphs + +.Normal +---- +include::{includedir}/ex-text.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-para] +==== + +.Literal +---- +include::{includedir}/ex-literal.adoc[tag=b-imp] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp] +==== + +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-para] +---- + +[.result] +==== +include::{includedir}/ex-admon.adoc[tag=b-para] +==== + +NOTE: You can also create <>. + +.Lead paragraph +---- +include::{includedir}/ex-text.adoc[tag=b-lead] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-lead] +==== + +NOTE: The default Asciidoctor stylesheet automatically styles the first paragraph of the preamble as a lead paragraph. + +.More Paragraph, Admonition and Literal Block Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-para}[Paragraphs] +* {uri-literal}[Literal Text and Blocks] +* {uri-admon}[Admonitions] +**** + +== Formatted Text + +.Bold, Italic, and Monospace +---- +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-bold-italic-mono] +==== + +.Monospace vs codespan +---- +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=monospace-vs-codespan] +==== + +NOTE: The meaning of backtick (`pass:[`]`) and plus (`+`) changed in Asciidoctor 1.5.0. +Backticks only make the text monospaced, whereas pluses passthrough text without applying formatting. +See the <> for details. + +.Marks and Custom Styling +---- +include::{includedir}/ex-text.adoc[tag=css-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=css-all] +==== + +.Superscript and Subscript +---- +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-sub-sup] +==== + +.Curved Quotation Marks and Apostrophes (Smart Quotes) +---- +include::{includedir}/ex-text.adoc[tag=b-c-quote] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-c-quote] +==== + +.More Text Formatting Examples +**** +See these sections in the Asciidoctor User Manual for more information and examples. + +* {uri-bold}[Bold and Italic Formatting] +* {uri-quote}[Quotation Marks and Apostrophes] +* {uri-sub}[Subscript and Superscript] +* {uri-mono}[Monospace Formatting] +* {uri-css}[Custom Styling with Attributes] +* {uri-pass}[Passthrough Macros] +**** + +== Document Header + +IMPORTANT: A header is optional. + +CAUTION: The header may not contain blank lines and must be offset from the content by at least one blank line. + +.Title only +---- +include::{includedir}/ex-header-title.adoc[tag=b-base] +---- + +.Title and author line +---- +include::{includedir}/ex-author.adoc[tag=b-base] +---- + +TIP: Asciidoctor allows multiple authors in the author line. +Use the semi-colon character to separate each author. + +.Title, author line and revision line +---- +include::{includedir}/ex-rev.adoc[tag=b-base] +---- + +IMPORTANT: You cannot have a revision line without an author line. + +.Document header with attributes +---- +include::{includedir}/ex-header-attr.adoc[tag=b-base] +---- + +[#section-titles] +== Section Titles (Headings) + +.Article doctype +---- +include::{includedir}/ex-section.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-base] +==== + +WARNING: When using the article doctype (the default), you can only have one level-0 section title (i.e., the document title) and it must be in the document header. + +NOTE: The number of equal signs matches the heading level in the HTML output. +For example, _Section Level 1_ becomes an `

` heading. + +.Book doctype +---- +include::{includedir}/ex-section.adoc[tag=book] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-book] +==== + +//// +IMPORTANT: There are two other ways to define a section title. +_Their omission is intentional_. +They both require more markup and are therefore unnecessary. +The https://en.wikipedia.org/wiki/Setext[setext] title syntax (underlined text) is especially wasteful, hard to remember, hard to maintain and error prone. +The reader never sees the extra markup, so why type it? +*Be frugal!* +//// + +.Explicit id +---- +[#primitives-nulls] +== Primitive types and null values +---- + +.Section anchors and links (Asciidoctor only) + +`sectanchors`:: +When this document attribute is set, a section icon anchor appears in front of the section title. + +`sectlinks`:: +When this document attribute is set, the section titles become self-links. +This enables a reader to bookmark the section. + +NOTE: Section title anchors depend on the default Asciidoctor stylesheet to render properly. + +== Include Files + +.Document parts +---- +include::{includedir}/ex-include.adoc[tag=base] +---- + +CAUTION: Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. +Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed. + +.Include content from a URI +---- +include::{includedir}/ex-include.adoc[tag=uri] +---- + +NOTE: Including content from a URI is potentially dangerous, so it's disabled if the safe mode is SECURE or greater. +Assuming the safe mode is less than SECURE, you must also set the `allow-uri-read` attribute to permit Asciidoctor to read content from a URI. + +== Breaks + +.Hard line break +---- +include::{includedir}/ex-text.adoc[tag=hb-all] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=hb-all] +==== + +.Thematic break (aka horizontal rule) +---- +include::{includedir}/ex-hr.adoc[tag=in-between] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=in-between] +==== + +.Page break +---- +<<< +---- + +== Lists + +.Unordered, basic +---- +include::{includedir}/ex-ulist.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base] +==== + +.Unordered, basic (alt) +---- +include::{includedir}/ex-ulist.adoc[tag=base-alt] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=base-alt] +==== + +NOTE: A blank line is required before and after a list to separated it from other blocks. + +TIP: You can force two adjacent lists apart by inserting a blank line followed by a line comment after the first list. +The convention is to use `//-` as the line comment to provide a hint to other authors that it's a list divider. + +.Unordered, max nesting +---- +include::{includedir}/ex-ulist.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=max] +==== + +TIP: The unordered list marker can be changed using {uri-marker}[block styles]. + +.Ordered, basic +---- +include::{includedir}/ex-o-list.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=b-base] +==== + +NOTE: You can choose to include an ordinal in front of each list marker, but they have to be in sequence. + +.Ordered, nested +---- +include::{includedir}/ex-o-list.adoc[tag=nest] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=nest] +==== + +.Ordered, max nesting +---- +include::{includedir}/ex-o-list.adoc[tag=max] +---- + +[.result] +==== +include::{includedir}/ex-o-list.adoc[tag=max] +==== + +TIP: For ordered lists, Asciidoctor supports {uri-list-num}[numeration styles] such as `lowergreek` and `decimal-leading-zero`. + +.Checklist +---- +include::{includedir}/ex-ulist.adoc[tag=check] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=check] +==== + +TIP: Checklists can use {uri-checklist}[font-based icons and be interactive]. + +.Description, single-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base] +==== + +.Description, multi-line +---- +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=b-base-multi] +==== + +.Q&A +---- +include::{includedir}/ex-dlist.adoc[tag=qa] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=qa] +==== + +.Mixed +---- +include::{includedir}/ex-dlist.adoc[tag=3-mix] +---- + +[.result] +==== +include::{includedir}/ex-dlist.adoc[tag=3-mix] +==== + +TIP: Lists can be indented. +Leading whitespace is not significant. + +.Complex content in outline lists +---- +include::{includedir}/ex-ulist.adoc[tag=b-complex] +---- + +[.result] +==== +include::{includedir}/ex-ulist.adoc[tag=b-complex] +==== + +== Links + +.External +---- +include::{includedir}/ex-url.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-base] +==== + +.With spaces and special characters +---- +include::{includedir}/ex-url.adoc[tag=b-spaces] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-spaces] +==== + +.Windows path +---- +include::{includedir}/ex-url.adoc[tag=b-windows] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-windows] +==== + +.Relative +---- +link:index.html[Docs] +---- + +[.result] +==== +link:index.html[Docs] +==== + +.Email and IRC +---- +include::{includedir}/ex-url.adoc[tag=b-scheme] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-scheme] +==== + +.Link with attributes (Asciidoctor only) +---- +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +---- + +[.result] +==== +include::{includedir}/ex-url.adoc[tag=b-linkattrs] +==== + +NOTE: Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. +To enable them prior to 1.5.7, you must set the `linkattrs` attribute on the document. +Since 1.5.7, attribute parsing is enabled automatically if an equal sign follows a comma. +When attribute parsing is enabled, you must quote the link text if it contains a comma. + +.Inline anchors +---- +include::{includedir}/ex-xref.adoc[tag=anchor] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=anchor] +==== + +.Internal cross references +---- +include::{includedir}/ex-xref.adoc[tag=b-base] +---- + +[.result] +==== +include::{includedir}/ex-xref.adoc[tag=b-base] +==== + +.Inter-document cross references (Asciidoctor only) +---- +include::{includedir}/ex-xref.adoc[tag=b-inter] +---- + +== Images + +Images are resolved relative to the value of the {uri-imagesdir}[imagesdir] document attribute, which is empty by default. +You are encouraged to make use of the `imagesdir` attribute to avoid hard-coding the common path to your images in every image macro. + +The `imagesdir` attribute can be an absolute path, relative path, or base URL. +When the image target is a URL or absolute path, the imagesdir prefix is _not_ prepended. + +.Block +---- +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=base] + +include::{includedir}/ex-image.adoc[tag=alt] + +include::{includedir}/ex-image.adoc[tag=attr] + +include::{includedir}/ex-image.adoc[tag=ab-url] +==== + +.Inline +---- +include::{includedir}/ex-image.adoc[tag=in] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in] +==== + +IMPORTANT: Two colons following the image keyword in the macro (i.e., `image::`) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., `image:`) indicates an inline image. +(All macros follow this pattern). +You use an inline image when you need to place the image in a line of text. +Otherwise, you should prefer the block form. + +.Inline image with positioning role +---- +include::{includedir}/ex-image.adoc[tag=in-role] +---- + +[.result] +==== +include::{includedir}/ex-image.adoc[tag=in-role] +==== + +TIP: There are a variety of attributes available to {uri-image-attrs}[position and frame images]. + +.Embedded +---- +include::{includedir}/ex-image.adoc[tag=data] +---- + +NOTE: When the `data-uri` attribute is set, all images in the document--including admonition icons--are embedded into the document as {uri-data-uri}[data URIs]. + +TIP: Instead of declaring the `data-uri` attribute in the document, you can pass it as a command-line argument using `-a data-uri`. + +== Videos + +.Block +---- +include::{includedir}/ex-video.adoc[tag=base] + +include::{includedir}/ex-video.adoc[tag=attr] +---- + +.Embedded Youtube video +---- +include::{includedir}/ex-video.adoc[tag=you] +---- + +.Embedded Vimeo video +---- +include::{includedir}/ex-video.adoc[tag=vim] +---- + +TIP: You can control the video settings using {uri-video}[additional attributes and options] on the macro. + +== Source Code + +.Inline (monospace only) +---- +include::{includedir}/ex-text.adoc[tag=b-mono-code] +---- + +[.result] +==== +include::{includedir}/ex-text.adoc[tag=b-mono-code] +==== + +.Inline (literal) +---- +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=backtick-plus] +==== + +.Literal line +---- +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-imp-code] +==== + +.Literal block +---- +include::{includedir}/ex-literal.adoc[tag=b-block] +---- + +[.result] +==== +include::{includedir}/ex-literal.adoc[tag=b-block] +==== + +[listing] +.Listing block with title, no syntax highlighting +.... +include::{includedir}/ex-listing.adoc[tag=b-base] +.... + +[.result] +==== +include::{includedir}/ex-listing.adoc[tag=b-base] +==== + +[listing] +.Code block with title and syntax highlighting +.... +include::{includedir}/ex-src.adoc[tag=src-base] +.... + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-base] +==== + +[listing,subs=specialchars] +.Code block with callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-src] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-src] +==== + +[listing,subs=specialchars] +.Code block with non-selectable callouts +.... +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=b-nonselect] +==== + +[listing,subs=specialchars] +.XML code block with a non-selectable callout +.... +include::{includedir}/ex-callout.adoc[tag=source-xml] +.... + +[.result] +==== +include::{includedir}/ex-callout.adoc[tag=source-xml] +==== + +[listing] +.Code block sourced from file +.... +include::{includedir}/ex-src.adoc[tag=src-inc] +.... + +[listing] +.Code block sourced from file relative to source directory +.... +include::{includedir}/ex-src.adoc[tag=rel] +.... + +[listing] +.Strip leading indentation from source +.... +include::{includedir}/ex-src.adoc[tag=ind] +.... + +[NOTE] +==== +* When `indent` is 0, the leading block indent is stripped (tabs are replaced with 4 spaces). +* When `indent` is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value. +==== + +.Code block without delimiters (no blank lines) +---- +include::{includedir}/ex-src.adoc[tag=src-para] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=src-para] +==== + +[IMPORTANT] +.Enabling the syntax highlighter +==== +Syntax highlighting is enabled by setting the `source-highlighter` attribute in the document header or passed as an argument. + + :source-highlighter: pygments + +The valid options are `coderay`, `highlightjs`, `prettify`, and `pygments`. +==== + +== More Delimited Blocks + +.Sidebar +---- +include::{includedir}/ex-sidebar.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-sidebar.adoc[tag=base] +==== + +NOTE: Any block can have a title, positioned above the block. +A block title is a line of text that starts with a dot. +The dot cannot be followed by a space. + +.Example +---- +include::{includedir}/ex-example.adoc[tag=base] +---- + +[example.result] +-- +include::{includedir}/ex-example.adoc[tag=base] +-- + +[#admon-bl] +.Admonition +---- +include::{includedir}/ex-admon.adoc[tag=b-bl] +---- + +[.result] +===== +include::{includedir}/ex-admon.adoc[tag=b-bl] +===== + +[TIP] +.Admonition and callout icons +==== +Asciidoctor can "`draw`" icons using {uri-fontawesome}[Font Awesome^] and CSS. + +To use this feature, set the value of the `icons` document attribute to `font`. +Asciidoctor will then emit HTML markup that selects an appropriate font character from the Font Awesome font for each admonition block. + +Icons can also be used {uri-icon-in}[inline] and {uri-icon-attrs}[styled]. +==== + +.Blockquote +---- +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=bl] + +include::{includedir}/ex-quote.adoc[tag=para] + +include::{includedir}/ex-quote.adoc[tag=no-cite] + +include::{includedir}/ex-quote.adoc[tag=link-text] +==== + +.Abbreviated blockquote (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=abbr] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=abbr] +==== + +.Air quotes: the best thing since fenced code blocks (Asciidoctor only) +---- +include::{includedir}/ex-quote.adoc[tag=air] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=air] +==== + +.Passthrough +---- +include::{includedir}/ex-pass.adoc[tag=b-bl] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-bl] +==== + +.Open +---- +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +---- + +[.result] +==== +include::{includedir}/ex-open.adoc[tag=base] + +include::{includedir}/ex-open.adoc[tag=src] +==== + +[listing] +.Custom substitutions +.... +include::{includedir}/ex-listing.adoc[tag=subs] +.... + +[.result] +==== +// the attribute value is hard-coded in this result since the example depends +// on a hypothetical document attribute +include::{includedir}/ex-listing.adoc[tag=subs-out] +==== + +== Block Id, Role and Options + +.Traditional (longhand) markup method for assigning block id and role +---- +[[goals]] +[role="incremental"] +* Goal 1 +* Goal 2 +---- + +.Shorthand markup method for assigning block id and role (Asciidoctor only) +---- +[#goals.incremental] +* Goal 1 +* Goal 2 +---- + +[TIP] +==== +* To specify multiple roles using the shorthand syntax, separate them by dots. +* The order of `id` and `role` values in the shorthand syntax does not matter. +==== + +.Traditional (longhand) markup method for assigning quoted text anchor (id) and role +---- +[[free_the_world]][big goal]_free the world_ +---- + +.Shorthand markup method for assigning quoted text anchor (id) and role (Asciidoctor only) +---- +[#free_the_world.big.goal]_free the world_ +---- + +.Role assigned to text enclosed in backticks +---- +[.rolename]`monospace text` +---- + +.Traditional (longhand) markup method for assigning block options +---- +[options="header,footer,autowidth"] +|=== +|Cell A |Cell B +|=== +---- + +.Shorthand markup method for assigning block options (Asciidoctor only) +---- +[%header%footer%autowidth] +|=== +|Cell A |Cell B +|=== +---- + +== Comments + +.Line +---- +include::{includedir}/ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::{includedir}/ex-comment.adoc[tag=bl] +---- + +== Tables + +.Table with a title, three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-base-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-base-h] +==== +<1> Unless the `cols` attribute is specified, the number of columns is equal to the number of cell separator characters on the first (non-blank) line between the block delimiters. +<2> When a blank line follows the first non-blank line, the cell in the first line get promoted to the table header. + +.Table with two columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-h-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-h] +==== +<1> The `+*+` in the `cols` attribute is the repeat operator. +It means repeat the column specification across the remaining of columns. +In this case, we are repeating the default formatting across 2 columns. +When the cells in the header are not defined on a single line, you must use the `cols` attribute to set the number of columns in the table and the `%header` option (or `options=header` attribute) to promote the first row to the table header. + +.Table with three columns, a header, and two rows of content +---- +include::{includedir}/ex-table.adoc[tag=b-col-indv-co] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-indv] +==== +<1> In this example, the `cols` attribute has two functions. +It specifies that this table has three columns, and it sets their relative widths. + +.Table with column containing AsciiDoc content +---- +include::{includedir}/ex-table.adoc[tag=b-col-a] +---- + +[.result] +==== +include::{includedir}/ex-table.adoc[tag=b-col-a] +==== + +.Table from CSV data +---- +include::{includedir}/ex-table-data.adoc[tag=csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=csv] +==== + +.Table from CSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-csv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-csv] +==== + +.Table from CSV data in file +---- +include::{includedir}/ex-table-data.adoc[tag=i-csv] +---- + +.Table from DSV data using shorthand (Asciidoctor only) +---- +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +---- + +[.result] +==== +include::{includedir}/ex-table-data.adoc[tag=s-dsv] +==== + +.Table with formatted, aligned and merged cells +---- +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +---- + +[.result] +==== +include::{includedir}/ex-table-cell.adoc[tag=b-spec] +==== + +== UI Macros + +IMPORTANT: You *must* set the `experimental` attribute in the document header to enable these macros. + +.Keyboard shortcuts (inline kbd macro) +---- +include::{includedir}/ex-ui.adoc[tag=key] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=key] +==== + +.Menu selections (inline menu macro) +---- +include::{includedir}/ex-ui.adoc[tag=menu] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=menu] +==== + +.Buttons (inline btn macro) +---- +include::{includedir}/ex-ui.adoc[tag=button] +---- + +[.result] +==== +include::{includedir}/ex-ui.adoc[tag=button] +==== + +== Attributes and Substitutions + +.Attribute declaration and usage +---- +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +---- + +[.result] +==== +// I have to use a nested doc hack here, otherwise the attributes won't resolve +[.unstyled] +|=== +a| +include::{includedir}/ex-header-attr.adoc[tag=b-attr] +|=== +==== + +.Attribute assignment precedence (highest to lowest) +- Attribute passed to the API or CLI that does not end in `@` +- Attribute defined in the document +- Attribute passed to the API or CLI that ends in `@` +- Intrinsic attribute value (default values) + +TIP: To make an attribute value that is passed to the API or CLI have a lower precedence than an assignment in the document, add an `@` symbol to the end of the attribute value. + +// Table of predefined attributes for character replacements +include::{includedir}/attrs-charref.adoc[tag=table] + +// Table of environment attributes +include::{includedir}/attrs-env.adoc[tag=table] + +.Named substitutions +include::{includedir}/subs-apply.adoc[tag=group] + +.Counter attributes +---- +include::{includedir}/ex-counter.adoc[tag=base] +---- + +[.result] +==== +include::{includedir}/ex-counter.adoc[tag=base] +==== + +== Text Replacement + +// Table of text replacements performed during replacements substitution +include::{includedir}/subs-symbol-repl.adoc[] + +TIP: Any named, numeric or hexadecimal {uri-char-xml}[XML character reference] is supported. + +== Escaping Text + +.Backslash +---- +include::{includedir}/ex-subs.adoc[tag=b-slash] +---- + +[.result] +==== +include::{includedir}/ex-subs.adoc[tag=b-slash] +==== + +.Passthrough ("`plus for passthrough`") +---- +include::{includedir}/ex-pass.adoc[tag=plus] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=plus] +==== + +//// +.Double dollar +---- +include::{includedir}/ex-pass.adoc[tag=b-dollar] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-dollar] +==== +//// + +.Raw (triple plus and inline pass macro) +---- +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-3p-macro] +==== + +//// +.Backticks +---- +include::{includedir}/ex-pass.adoc[tag=b-tick] +---- + +[.result] +==== +include::{includedir}/ex-pass.adoc[tag=b-tick] +==== +//// + +== Table of Contents (ToC) + +.Document with ToC +---- +include::{includedir}/ex-toc.adoc[tag=base] +---- + +.Document with ToC positioned on the right +---- +include::{includedir}/ex-toc.adoc[tag=pos] +---- + +TIP: The ToC {uri-toc}[title, levels, and positioning] can be customized. + +== Bibliography + +.Bibliography with inbound references +---- +include::{includedir}/ex-biblio.adoc[tag=base] +---- + +[.result] +==== +|=== +a| +include::{includedir}/ex-biblio.adoc[tag=base] +|=== +==== + +[#section-footnotes] +== Footnotes + +.Normal and reusable footnotes +---- +include::{includedir}/ex-footnote.adoc[tag=base] +---- + +[.result] +==== +[.unstyled] +|=== +a| +include::{includedir}/ex-footnote.adoc[tag=base] +|=== +==== + +[#markdown-compatibility] +== Markdown Compatibility + +Markdown compatible syntax is only available when using Asciidoctor. + +.Markdown-style headings +---- +include::{includedir}/ex-section.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-section.adoc[tag=b-md] +==== + +.Fenced code block with syntax highlighting +---- +include::{includedir}/ex-src.adoc[tag=fence] +---- + +[.result] +==== +include::{includedir}/ex-src.adoc[tag=fence] +==== + +.Markdown-style blockquote +---- +include::{includedir}/ex-quote.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md] +==== + +.Markdown-style blockquote with block content +---- +include::{includedir}/ex-quote.adoc[tag=md-alt] +---- + +[.result] +==== +include::{includedir}/ex-quote.adoc[tag=md-alt] +==== + +.Markdown-style horizontal rules +---- +include::{includedir}/ex-hr.adoc[tag=md] +---- + +[.result] +==== +include::{includedir}/ex-hr.adoc[tag=md] +==== + +== User Manual and Help + +To learn more about Asciidoctor and its capabilities, check out the other {docs}[Asciidoctor guides] and its {user}[User Manual]. +Also, don't forget to join the {uri-mailinglist}[Asciidoctor mailing list], where you can ask questions and leave comments. + + + + + + + + + + + + + +.If you need to convert only one file +[NOTE] +==== +``` +docker run --rm -v $(pwd):/documents/ registry.vlabs.uniwa.gr:5080/swarmlab-asciidoctor asciidoctor --safe -b html5 -a theme=flask -a toc2 -a toc-placement=right -o ./path/to/FILENAME.html ./path/from/FILENAME.adoc +``` +Please note, there is a **.** in ./path +==== + + + + + + + +:hardbreaks: + +{empty} + +{empty} + +{empty} + +:!hardbreaks: + +''' + +.Reminder +[NOTE] +==== +:hardbreaks: +Caminante, no hay camino, +se hace camino al andar. + +Wanderer, there is no path, +the path is made by walking. + +*Antonio Machado* Campos de Castilla +==== diff --git a/asciidoc/_includes/about-asciidoctor.adoc b/asciidoc/_includes/about-asciidoctor.adoc new file mode 100644 index 0000000..07cc32a --- /dev/null +++ b/asciidoc/_includes/about-asciidoctor.adoc @@ -0,0 +1,34 @@ +//// +user manual +//// + +== What is Asciidoctor? + +//// +{homepage}[Asciidoctor] is an open source text processor and publishing toolchain for transforming AsciiDoc markup into HTML 5, EPUB3, PDF, DocBook 5.0 and 4.5, slidedecks, and other custom formats. +Asciidoctor is written entirely in Ruby, packaged as a RubyGem and published to {gem}[RubyGems.org]. +There are also Fedora, Debian and Ubuntu packages available for installing Asciidoctor. +The git repositories for the project are hosted under the {gh-org}[Asciidoctor organization on GitHub]. +//// + +Asciidoctor is a _fast_ text processor and publishing toolchain for converting AsciiDoc content to HTML5, EPUB3, PDF, DocBook 5 (or 4.5) slidedecks and other formats. +Asciidoctor is written in Ruby, packaged as a RubyGem and published to {uri-gem}[RubyGems.org]. +The gem is also packaged in several Linux distributions, including Fedora, Debian and Ubuntu. +Asciidoctor is open source, {uri-repo}[hosted on GitHub], and released under the MIT license. + +=== The Big Picture + +Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. +Asciidoctor adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant out-of-the-box experience. + +image::zen-screenshot.png[Preview of AsciiDoc source and corresponding HTML] + +=== Asciidoctor on the JVM + +You can run Asciidoctor on the JVM using JRuby. +You can also use {uri-asciidoctorj}[AsciidoctorJ] to invoke Asciidoctor's APIs from Java and other JVM languages. + +=== Asciidoctor.js + +Asciidoctor can be used in JavaScript. +https://opalrb.com[Opal] is used to transcompile the code from Ruby to JavaScript to make {uri-asciidoctorjs}[Asciidoctor.js], which can be used wherever JavaScript runs, such as in a web browser or on Node.js. diff --git a/asciidoc/_includes/abstract.adoc b/asciidoc/_includes/abstract.adoc new file mode 100644 index 0000000..cecbfc2 --- /dev/null +++ b/asciidoc/_includes/abstract.adoc @@ -0,0 +1,76 @@ +//// +Included in: + +- user-manual +//// + +An abstract is a concise overview of an article or of a chapter in a book. +They are frequently found in the frontmatter of academic, research, and analytical papers. +//Abstracts with subheadings are structured abstracts, whereas abstracts without subheadings are unstructured. +//^ Not relevant for AsciiDoc +A complete (i.e., informative) abstract states the key topics and findings while a limited (i.e., descriptive) abstract briefly describes the structure of the content. + +The abstract may be written using a section, open block, or paragraph and must bear the abstract style. +If used, the abstract must appear before the first section of an article (at the start of the <>) or at the start of a chapter in a book. +An abstract may not be used _before_ a part or chapter in a book. + +Here's an example of an abstract at the beginning of an article, defined using a section: + +[source] +---- += Article Title + +[abstract] +== Abstract + +Documentation is a distillation of many long, squiggly adventures. + +== First Section +---- + +Here's an example of the same abstract defined using a paragraph: + +[source] +---- += Article Title + +[abstract] +.Abstract +Documentation is a distillation of many long, squiggly adventures. + +== First Section +---- + +In the book doctype, the abstract section must be a level below the chapter. + +[source] +---- +== Chapter Title + +[abstract] +=== Chapter Abstract + +Documentation is a distillation of many long, squiggly adventures. + +=== First Section +---- + +An abstract defined using an open block or paragraph does not require a title and does not depend on a subsequent section to terminate. + +[source] +---- += Article Title + +[abstract] +.Optional Abstract Title +-- +This article will take you on a wonderful adventure of knowledge. + +You'll start with the basics. +Beyond that, where you go is up to you. +-- + +Your journey begins here. +---- + +TIP: To include a quote at the beginning of a chapter in a book, wrap the quote block inside an abstract block. diff --git a/asciidoc/_includes/admonition.adoc b/asciidoc/_includes/admonition.adoc new file mode 100644 index 0000000..a49228e --- /dev/null +++ b/asciidoc/_includes/admonition.adoc @@ -0,0 +1,87 @@ +//// +Included in: + +- user-manual: Admonition +- writers-guide: admonition +//// + +// tag::intro[] +There 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. +These are called admonitions. +It's rendered style is determined by the assigned label (i.e., value). +Asciidoctor provides five admonition style labels: + +* `NOTE` +* `TIP` +* `IMPORTANT` +* `CAUTION` +* `WARNING` + +.Caution vs. Warning +**** +When choosing the admonition type, you may find yourself getting confused between "caution" and "warning" as these words are often used interchangeably. +Here's a simple rule to help you differentiate the two: + +* Use *CAUTION* to advise the reader to _act_ carefully (i.e., exercise care). +* Use *WARNING* to inform the reader of danger, harm, or consequences that exist. + +To find a deeper analysis, see https://www.differencebetween.com/difference-between-caution-and-vs-warning/. +**** + +When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use. +The label must be uppercase and followed by a colon (`:`). + +.Admonition paragraph syntax +[source] +---- +include::ex-admon.adoc[tag=para-c] +---- +<1> The label must be uppercase and immediately followed by a colon (`:`). +<2> Separate the first line of the paragraph from the label by a single space. +// end::intro[] + +:icons!: +// tag::icon[] +.Result: Admonition paragraph +==== +include::ex-admon.adoc[tag=para] +==== +// end::icon[] +:icons: font + +When you want to apply an admonition to complex content, set the label as a style attribute on a block. +As seen in the next example, admonition labels are commonly set on example blocks. +This behavior is referred to as *masquerading*. +The label must be uppercase when set as an attribute on a block. + +.Admonition block syntax +[source] +---- +include::ex-admon.adoc[tag=bl-c] +---- +<1> Set the label in an attribute list on a delimited block. The label must be uppercase. +<2> Admonition styles are commonly set on example blocks. Example blocks are delimited by four equal signs (`====`). + +:icons!: +.Result: Admonition block +==== +include::ex-admon.adoc[tag=bl-nest] +==== +:icons: font + +In the examples above, the admonition is rendered in a callout box with the style label in the gutter. +You can replace the textual labels with icons by setting the `icons` attribute on the document. +This is how the WARNING admonition paragraph renders when icons is set and assigned the `font` value. + +.Admonition paragraph with icons set +[source] +---- +include::ex-admon.adoc[tag=para] +---- + +.Result: Admonition paragraph with icons set +==== +include::ex-admon.adoc[tag=para] +==== + +Learn more about using Font Awesome or custom icons with admonitions in the <> section. diff --git a/asciidoc/_includes/api-intro.adoc b/asciidoc/_includes/api-intro.adoc new file mode 100644 index 0000000..c1fbef0 --- /dev/null +++ b/asciidoc/_includes/api-intro.adoc @@ -0,0 +1,11 @@ +//// +API introduction for Asciidoctor +This file is included in the user-manual documents +//// + +In addition to the command line interface, Asciidoctor provides a Ruby API. +The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub. + +Asciidoctor also has a Java API that mirrors the Ruby API. +The Java API calls through to the Ruby API using an embedded JRuby runtime. +See the {doc-asciidoctorj}[AsciidoctorJ project] for more information. diff --git a/asciidoc/_includes/appendix.adoc b/asciidoc/_includes/appendix.adoc new file mode 100644 index 0000000..05a2934 --- /dev/null +++ b/asciidoc/_includes/appendix.adoc @@ -0,0 +1,79 @@ +//// +Included in: + +- user-manual +//// + +You can indicate that a section, part, or chapter is an appendix by adding an `[appendix]` line above the section title. + +[source] +---- +[appendix] +== Copyright and License +---- + +While the AsciiDoc structure allows appendices to be placed anywhere, it's customary to place them at the end of the document, after all other sections. + +Sections marked as appendix have a different title, which is built as follows: + +* A fixed prefix (taken from the value of the `appendix-caption` attribute, which defaults to "`Appendix`") +* A letter that represents the number of this appendix within the sequence of appendices (A, B, C, ...) +* A colon +* The original section title + +For example: + + Appendix A: Copyright and License + +The prefix can be modified by defining the `appendix-caption` attribute. +This value can be changed using: + +[source] +---- +:appendix-caption: Appx +---- + +Or it can be unset using: + +[source] +---- +:appendix-caption!: +---- + +Appendices can have subsections. +However, there are some rules to follow depending on which type of document you are creating. + +For articles, the appendix must be defined as a level-1 section. +(If a level-0 section is used, a level-1 section is implied). +For example: + +[source] +---- +include::ex-appendix.adoc[tag=appx-article] +---- + +The table of contents will appear as follows: + +[source] +---- +include::ex-appendix.adoc[tag=appx-article-out] +---- + +For books, the appendix must be defined as a level-1 section if you want the appendix to be a adjacent to other chapters (and in the current part if the book has multiple parts). +In a multi-part book, if you want the appendix to be adjacent to other parts, the appendix must be defined as a level-0 section. +In either case, the first subsection of the appendix must be a level-3 section, not a level-2 section. +That's because an appendix cannot contain chapters. + +The following example shows how to define an appendix for a multi-book (take away the part title if you're creating a simple book): + +[source] +---- +include::ex-appendix.adoc[tag=appx-book] +---- + +The table of contents will appear as follows: + +[source] +---- +include::ex-appendix.adoc[tag=appx-book-out] +---- diff --git a/asciidoc/_includes/apply-theme.adoc b/asciidoc/_includes/apply-theme.adoc new file mode 100644 index 0000000..bb13e91 --- /dev/null +++ b/asciidoc/_includes/apply-theme.adoc @@ -0,0 +1,93 @@ +//// +Custom Themes +Applying a theme + +This document is included in: + +- user-manual +- produce-custom-themes-using-asciidoctor-stylesheet-factory +//// + +A custom stylesheet can be stored in the same directory as your document or in a separate directory. +Like the default stylesheet, you can have the output document link to your custom stylesheet or embed it. + +If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI. + + $ asciidoctor -a stylesheet=mystyles.css mysample.adoc + +. Save your custom stylesheet in the same directory as `mysample.adoc` +. Call the `asciidoctor` processor +. Set `-a` (`--attribute`) and `stylesheet` +. Assign the stylesheet file's name to the `stylesheet` attribute +. Enter your document file's name. + +Alternatively, let's set the `stylesheet` attribute in the header of `mysample.adoc`. + +---- +include::mysample-stylesheet.adoc[] +---- + +==== +image::mysample-stylesheet.png[] +==== + +When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document. +Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet. +Let's move `mystyles.css` into `mydocuments/mystylesheets/`. +Our AsciiDoc document, `mysample.adoc`, is saved in the `mydocuments/` directory. + +---- +include::mysample-stylesdir.adoc[] +---- + +After processing `mysample.adoc`, its HTML output (`mysample.html`), which includes the embedded `mystyles.css` stylesheet, is created in the `mydocuments/` directory. + +==== +image::mysample-stylesdir-dir.png[] +==== + +You can also set `stylesdir` in the CLI. + + $ asciidoctor -a stylesdir=mystylesheets/ -a stylesheet=mystyles.css mysample.adoc + +If you don't want to embed the `mystyles.css` stylesheet into your HTML output, make sure to set `linkcss`. + +---- +include::mysample-stylesdir-link.adoc[] +---- + +After your document is converted, notice that a copy of `mystyles.css` was not created in the `mydocuments/` directory. +Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved. + +[#style-nest-doc] +.Stylesheets and processing multiple nested documents +**** +When you are <>, it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents. +This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories. +One way to solve this problem is to maintain the path to `stylesdir` in each document. + +Let's say you have three AsciiDoc documents saved in the following directory structure: + +---- +/mydocuments + a.adoc + b.adoc + /mynesteddocuments + c.adoc + /mystylesheets +---- + +For `a.adoc` and `b.adoc`, set `stylesdir` to: + +---- +:stylesdir: mystylesheets +---- + +For `c.adoc`, set `stylesdir` to: + +---- +:stylesdir: ../mystylesheets +---- + +If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet. +**** diff --git a/asciidoc/_includes/asciidoc-article-template.adoc b/asciidoc/_includes/asciidoc-article-template.adoc new file mode 100644 index 0000000..db0acf1 --- /dev/null +++ b/asciidoc/_includes/asciidoc-article-template.adoc @@ -0,0 +1,91 @@ += AsciiDoc Article Title +Firstname Lastname +1.0, July 29, 2014, Asciidoctor 1.5 article template +:toc: +:icons: font +:quick-uri: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ + +Content entered directly below the header but before the first section heading is called the preamble. + +== First level heading + +This is a paragraph with a *bold* word and an _italicized_ word. + +.Image caption +image::image-file-name.png[I am the image alt text.] + +This is another paragraph.footnote:[I am footnote text and will be displayed at the bottom of the article.] + +=== Second level heading + +.Unordered list title +* list item 1 +** nested list item +*** nested nested list item 1 +*** nested nested list item 2 +* list item 2 + +This is a paragraph. + +.Example block title +==== +Content in an example block is subject to normal substitutions. +==== + +.Sidebar title +**** +Sidebars contain aside text and are subject to normal substitutions. +**** + +==== Third level heading + +[#id-for-listing-block] +.Listing block title +---- +Content in a listing block is subject to verbatim substitutions. +Listing block content is commonly used to preserve code input. +---- + +===== Fourth level heading + +.Table title +|=== +|Column heading 1 |Column heading 2 + +|Column 1, row 1 +|Column 2, row 1 + +|Column 1, row 2 +|Column 2, row 2 +|=== + +====== Fifth level heading + +[quote, firstname lastname, movie title] +____ +I am a block quote or a prose excerpt. +I am subject to normal substitutions. +____ + +[verse, firstname lastname, poem title and more] +____ +I am a verse block. + Indents and endlines are preserved in verse blocks. +____ + +== First level heading + +TIP: There are five admonition labels: Tip, Note, Important, Caution and Warning. + +// I am a comment and won't be rendered. + +. ordered list item +.. nested ordered list item +. ordered list item + +The text at the end of this sentence is cross referenced to <<_third_level_heading,the third level heading>> + +== First level heading + +This is a link to the https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. +This is an attribute reference {quick-uri}[which links this text to the Asciidoctor Quick Reference Guide]. diff --git a/asciidoc/_includes/asciidoctor-ant.adoc b/asciidoc/_includes/asciidoctor-ant.adoc new file mode 100644 index 0000000..cb441a4 --- /dev/null +++ b/asciidoc/_includes/asciidoctor-ant.adoc @@ -0,0 +1,22 @@ +//== Apache Ant + +The `asciidoctor-ant` task is an all-in-one solution for running Asciidoctor from Ant. +It is based on AsciidoctorJ and JRuby, both of which are encapsulated in a single jar file. + +Usage is: + +[source,xml] +-- + +... + + + + +... + +-- + +For more details, see {uri-anttask}[asciidoctor-ant on GitHub]. diff --git a/asciidoc/_includes/attr-doc.adoc b/asciidoc/_includes/attr-doc.adoc new file mode 100644 index 0000000..eae0885 --- /dev/null +++ b/asciidoc/_includes/attr-doc.adoc @@ -0,0 +1,310 @@ +//// +Included in: + +- user-manual: Attributes: Setting attributes on a document +//// + +An [.term]_attribute entry_ is the primary mechanism for defining a document attribute in an AsciiDoc document. +You can think of an attribute entry as a global variable assignment for AsciiDoc. +The document attribute it creates becomes available from that point forward in the document. +Attribute entries are also frequently used to toggle features. + +An attribute entry consists of two parts: an attribute name and an attribute value. +The attribute name comes first. +It must be at the start of the line and must be enclosed in colons (e.g., `:name:`). +If present, the attribute value is offset from the name part by at least one space (e.g., `:name: value`). +Be aware that substitutions automatically get applied to the value by default, as described in <>. + +.Anatomy of an attribute entry +[source] +---- +:name: value +---- + +The attribute value is optional. +A blank value is often used to set (i.e., activate) a boolean attribute (thus making a blank value implicitly true). + +.Anatomy of an attribute entry to set a boolean attribute +[source] +---- +:name: +---- + +An exclamation point (`!`) before (or after) the attribute name unsets the attribute. +In this case, the value is ignored. + +.Anatomy of an attribue entry to unset an attribute +[source] +---- +:!name: +---- + +Attribute entries have the following characteristics: + +Attributes entries can: :: +* be assigned to a document: +** through the CLI or API +** in the document's header +** in the document's body +* be unset (turned off) with a leading (or trailing) `!` added to the name +* have default values (in the case of a built-in attribute) +* have alternate values (in the case of a built-in attribute) +* span multiple, contiguous lines +* include inline AsciiDoc content + +Attribute entries can not: :: +* override locked attributes assigned from the command line +* include AsciiDoc block content (such as, bulleted lists or other types of whitespace-dependent markup) + +Attributes are typically defined in the document header, though they may also be defined in the body of the document. +Once set, an attribute (and its value) are available for use for the remainder of the document. +Unless locked by the API, attributes may be reassigned at any subsequent point in the document. + +==== Attribute entry use cases + +Attributes entries serve three main purposes: + +. Toggle or configure built-in features +. Set built-in asset locations +. Content reuse + +===== Setting built-in attributes + +Numerous attribute are reserved for special purposes. +These built-in attributes can be used to toggle behavior, such as the table of contents, or control the generated output, such as selecting or configuring a converter. +Many built-in attributes only take effect when defined in the document header. + +For example, to enable the built-in table of contents, you can define (i.e., set) the `toc` attribute using an attribute entry in the document header as follows: + +[source] +---- +:toc: +---- + +When the value following an attribute is left empty, as it is in the example above, the default value will be assigned (if any). +The default value for `toc` is `auto`. +Therefore, the table of contents will be placed in the default location (below the document's title) when the document is converted. + +If you want the table of contents to be placed on the right side of the document, you must assign the attribute a new value. + +[source] +---- +:toc: right +---- + +The `right` value will override the default value of `auto`. +The value assigned to an attribute in the document header replaces the intrinsic value (assuming the attribute is not locked). + +===== Setting asset locations + +You can also use attributes to set the base path to images (default: _empty_), icons (default: `./images/icons`), and stylesheets (default: `./stylesheets`). + +.Base asset path configuration example +[source] +---- +:imagesdir: ./images +:iconsdir: ./icons +:stylesdir: ./styles +---- + +===== Content reuse + +If you're familiar with writing in XML, you might recognize a document attribute as a user-defined entity. +When 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. + +A prime use case for attribute entries is to promote frequently used URLs and links to the top of the document. + +.URL attribute entry +[source] +---- +:url-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor +---- + +Now you can refer to this attribute entry anywhere in the document (where attribute substitution is performed) by surrounding its name in curly braces. + +Instead of having to type the URL out longhand in the link macro, as follows: + +.A case for using an attribute reference +[source] +---- +Did you know there's an https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]? +---- + +We can replace the target side of the link macro with a reference to our attribute. + +.url-fedpkg attribute usage example +[source] +---- +Did you know there's an {url-fedpkg}[Asciidoctor package for Fedora]? +---- + +To save even more typing, you can store the whole link in an attribute value. + +.Link attribute entry +[source] +---- +:link-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora] +---- + +Now you insert this link anywhere in the document using an attribute reference. + +.link-fedpkg attribute usage example +[source] +---- +Did you know there's an {link-fedpkg}? +---- + +Note that the link substitution occurs _after_ the attribute reference is resolved. +This works thanks to the default order of substitutions on a paragraph. +If you want the link macro to be resolved eagerly at the time the attribute is assigned, you need to enclose it in a pass macro. + +.Link attribute entry resolved eagerly +[source] +---- +:link-fedpkg: pass:m[https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]] +---- + +Now you can use this link in a section title (where the order of substitutions is different). +Let's dive deeper into which substitutions are applied to an attribute entry and how to alter them. + +[#attribute-entry-subs] +==== Substitutions in an attribute entry + +The AsciiDoc processor automatically applies substitutions from the header substitution group to the value of an attribute entry prior to the assignment (regardless of where the attribute entry is declared in the document). +The header substitution group replaces <> and <>. +This is the same group that gets applied to metadata lines (author and revision information) in the document header. +To learn about how these substitutions work, refer to the <> chapter. + +==== Altering attribute entry substitutions + +If you want the value of an attribute entry to be used *as is* (not subject to substitutions), or you want to alter the substitutions that are applied, you can enclose the value in the <> (i.e., `\pass:[]`). +The inline pass macro accepts a list of zero or more substitutions in the target slot, which can be used to control which substitutions are applied to the value. +If no substitutions are specified, no substitutions will be applied. + +In order for the inline macro to work in this context, it must completely surround the attribute value. +If it's used anywhere else in the value, it is ignored. + +Here's how to prevent substitutions from being applied to the value of an attribute entry: + +[source] +---- +:cols: pass:[.>2,.>4] +---- + +This might be useful if you're referencing the attribute in a place that depends on the unaltered text, such as the value of the `cols` attribute on a table. + +Here's how to apply the <> to the value of an attribute entry: + +[source] +---- +:app-name: pass:quotes[MyApp^2^] +---- + +Internally, the value is stored as `MyApp2`. +You can inspect the value stored in an attribute using this trick: + +[listing] +.... +[subs=attributes+] +---- +{app-name} +---- +.... + +You can also specify the substitution using the single-character alias, `q`. + +[source] +---- +:app-name: pass:q[MyApp^2^] +---- + +The inline pass macro kind of works like an attribute value preprocessor. +If the processor detects that an inline pass macro completely surrounds the attribute value, it: + +. reads the list of substitutions from the target slot of the macro +. unwraps the value from the macro +. applies the substitutions to the value + +If the macro is absent, the value is processed with the header substitution group. + +You can also change the substitutions that are applied to an attribute at the time it is resolved. +This is done by manipulating the substitutions applied to the text where it is referenced. +For example, here's how we could get the processor to apply quote substitutions to the value of an attribute: + +[source] +---- +:app-name: MyApp^2^ + +[subs="specialchars,attributes,quotes,replacements,macros,post_replacements"] +The application is called {app-name}. +---- + +Notice that we've swapped the order of the `attributes` and `quotes` substitutions. +This strategy is akin to postprocessing the attribute value. + +==== Splitting attribute values over multiple lines + +When an attribute value is very long, it's possible to split it (i.e., soft-wrap) across multiple lines. + +Let's assume we are working with the following attribute entry: + +.A long, single-line attribute +[source] +---- +:long-value: If you have a very long line of text that you need to substitute regularly in a document, you may find it easier to split it neatly in the header so it remains readable to the next person reading your docs code. +---- + +You can split the value over multiple lines to make it more readable by inserting a space followed by a backslash (i.e., `{sp}\`) at the end of each continuing line. + +.A long, multiline attribute (soft wrapped) +[source] +---- +:long-value: If you have a very long line of text \ +that you need to substitute regularly in a document, \ +you may find it easier to split it neatly in the header \ +so it remains readable to folks reading your docs code. +---- + +The backslash and the newline that follows will be removed from the attribute value when the attribute entry is parsed, making this second example effectively the same as the first. +The space before the backslash is preserved, so you have to use this technique at a natural break point in the content. + +You can force an attribute value to hard wrap by adding a plus surrounded by spaces before the backslash. + +.An attribute value with hard line breaks +[source] +---- +:haiku: Write your docs in text, + \ +AsciiDoc makes it easy, + \ +Now get back to work! +---- + +This syntax ensures that the newlines are preserved in the output document as hard line breaks. + +==== Attribute limitations + +Attributes let you do a surprising amount of formatting for what is fundamentally a text replacement tool. + +It may be tempting to try and extend attributes to be used for complex replaceable markup. + +Supported:: +Basic in-line AsciiDoc markup is permitted in attribute values, such as: ++ +* attribute references +* text formatting (usually wrapped in a pass macro) +* inline macros (usually wrapped in a pass macro) + +Unsupported:: +Complex AsciiDoc markup is not permitted in attribute values, such as: ++ +* lists +* multiple paragraphs +* other whitespace-dependent markup types + +//// +TODO: This section actually might make more sense in the header section. + +The main focus of the learning for this documentation is how to use inline formatting in an attribute value. Normally, inline formatting in an attribute value is not interpreted because: + +a. Inline formatting is not applied when an attribute is set (attribute holds raw value) +b. Inline formatting is not applied when an attribute is referenced since the relevant substitutions come before attributes are resolved +//// diff --git a/asciidoc/_includes/attr-element.adoc b/asciidoc/_includes/attr-element.adoc new file mode 100644 index 0000000..618f190 --- /dev/null +++ b/asciidoc/_includes/attr-element.adoc @@ -0,0 +1,63 @@ +//// +Included in: + +- user-manual: Attributes: Setting attributes on an element +//// + +// tag::intro[] +An attribute list can apply to blocks, inline quotes text, and macros. +The attributes and their values contained in the list will take precedence over attribute entries. + +.Anatomy of an attribute list + [positional_attribute1,positional_attribute2,name_attribute1="value"] + +Attribute lists: + +. apply to blocks as well as macros and inline quoted text +. can contain positional and named attributes +. take precedence over global attributes +// end::intro[] + +==== Positional attribute +// tag::pos[] +Positional attributes are un-named values at the start of the attribute list. +The attribute that they are assigned to depends on the type of the element: + +* `icon:` (1) size +* `image:` and `image::` (1) alt text, (2) width, (3) height +* Delimited blocks: (1) block name (aka style) +* Other inline quoted text: (1) role + +For example, the following two image macros are equivalent. + +[source,asciidoc] +---- +image::sunset.jpg[Sunset,300,400] + +image::sunset.jpg[alt=Sunset,width=300,height=400] +---- + +The second macro is just a duplicate of the first macro written out longhand. +// end::pos[] + +==== Named attribute +// tag::name[] +A named attribute consists of a name and a value separated by an `=` character (e.g., `name=value`). + +If the value contains a space, comma, or quote character, it must be enclosed in double or single quotes (e.g., `name="value with space"`). +In all other cases, the surrounding quotes are optional. +If present, the enclosing quotes are dropped from the parsed value. + +To undefine a named attribute, set the value to `None` (case sensitive). +// end::name[] + +==== Attribute List Substitutions +// tag::subs[] +Attribute references are expanded before the block attribute list is processed. +Therefore, it's not necessary to force substitutions to be applied if you simply want to use a document attribute reference in a block attribute. + +If the attribute name (for a positional attribute) or value (for a named attribute) is enclosed in single quotes (e.g., `+title='Processed by https://asciidoctor.org[Asciidoctor]'+`), <> are applied to the value at assignment time (with some exceptions). +No special processing is performed if the value is not enclosed in quotes or is enclosed in double quotes. + +If the attribute value contains the same quote character being used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., `title="\"Dark Horse\" is a song by George Harrison"`). +// end::subs[] diff --git a/asciidoc/_includes/attr-miss.adoc b/asciidoc/_includes/attr-miss.adoc new file mode 100644 index 0000000..1dc6e0b --- /dev/null +++ b/asciidoc/_includes/attr-miss.adoc @@ -0,0 +1,91 @@ +//// +Included in: + +- user-manual: Catch a missing or undefined attribute +//// + +As a result of a misconfigured document or inadvertent substitution, an attribute reference may point to a non-existent attribute (e.g., `+{does-not-exist}+`). +It could be that the attribute reference itself undefines the attribute (e.g., `+{set:attribute-no-more!}+`). +You'll want to think about how you want the processor to handle these situations and configure it accordingly. + +AsciiDoc Python simply drops any line that contains a reference to a missing attribute. +This "`feature`" was designed with AsciiDoc Python's own template language in mind, which is also based on the AsciiDoc syntax. +However, this behavior was never really intended for use in regular AsciiDoc documents. +The behavior is frustrating for the author, editor, or reader because it's not immediately obvious when a line goes missing. +Discovering the absence of certain line often requires a painstaking read-through of the document or section, if it's even noticed at all. + +Asciidoctor offers two attributes to alleviate this inconvenience: `attribute-missing` and `attribute-undefined`. + +===== Missing attribute + +The `attribute-missing` attribute controls how missing (i.e., unresolved) references are handled. +By default, missing references are left intact so the integrity of the document is preserved (`skip`). +However, that mode doesn't help the author track down these references. + +To help with that task, Asciidoctor can be configured to warn when a missing reference is encountered (`warn`). +Asciidoctor can also emulate the behavior of AsciiDoc Python (`drop-line`), or offer something in between (`drop`). + +Here are the four possible values of the `attribute-missing` attribute: + +`skip`:: leaves the reference intact without issuing a warning (default setting) +`drop`:: drops the reference, but not the whole line +`drop-line`:: drops the whole line on which the reference occurs (matches behavior of AsciiDoc Python) +`warn`:: leaves the reference intact, but also prints a warning about the missing attribute (recommended) + +Consider the following line of AsciiDoc: + +[source] +---- +Hello, {name}! +---- + +Here's how the line is handled in each case, assuming the `name` attribute is not defined: + +[horizontal] +`skip`:: Hello, \{name}! +`drop`:: Hello, ! +`drop-line`:: {empty} +`warn`:: ++ +---- +asciidoctor: WARNING: skipping reference to missing attribute: name +---- + +If you want the processor to fail when the document contains a missing attribute, set the `attribute-missing` attribute to `warn` and pass the `--failure-level=WARN` option to the processor. + + $ asciidoctor -a attribute-missing=warn --failure-level=WARN doc.adoc + +When using the API, you can consult the logger for the max severity of all messages reported or look for specific messages in the stack. + +There are several exceptions when the `attribute-missing` attribute is not strictly honored. +One of those cases is the include directive. +If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute and drop the include directive. +This behavior was chosen because showing the unresolved include directive to the reader is messy. + +Another case is the block image macro. +If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute, but leave the image macro unresolved so as to show it as alt text. + +A missing attribute reference can safely be used in an ifeval clause without any side effects (i.e., `drop`) since often the purpose of that statement is to determine whether an attribute resolves to a value. + +===== Undefined attribute + +The attribute attribute-undefined controls how expressions that undefine an attribute are handled. +By default, the line is dropped since the expression is a statement, not content. + +This attribute has two possible values: + +`drop`:: substitute the expression with an empty string after processing it +`drop-line`:: drop the line that contains this expression (default setting; matches behavior of AsciiDoc Python) + +The option `skip` doesn't make sense here since the statement is not intended to produce content. + +Consider the following declaration: + +``` +{set:name!} +``` + +Depending on whether attribute-undefined is `drop` or `drop-line`, either the statement or the line that contains it will be discarded. +It's reasonable to stick with the compliant behavior, drop-line, in this case. + +TIP: We recommend putting any statement that undefines an attribute on a line by itself. diff --git a/asciidoc/_includes/attr-style.adoc b/asciidoc/_includes/attr-style.adoc new file mode 100644 index 0000000..c94a86c --- /dev/null +++ b/asciidoc/_includes/attr-style.adoc @@ -0,0 +1,95 @@ +//// +Included in: + +- user-manual: Attributes: Style +//// + +// tag::intro[] +The style attribute is the first positional attribute in an attribute list. +It specifies a predefined set of characteristics that should apply to a block element or macro. + +For example, a paragraph block can be assigned one of the following built-in style attributes: + +* normal (default, so does not need to be set) +* literal +* verse +* quote +* listing +* TIP +* NOTE +* IMPORTANT +* WARNING +* CAUTION +* abstract +* partintro +* comment +* example +* sidebar +* source + +// end::intro[] + +==== Id +// tag::id[] +The id attribute specifies a unique name for an element. +That name can only be used once in a document. + +An id has two purposes: + +. to provide an internal link or cross reference anchor for the element +. to reference a style or script used by the output processor +// end::id[] + +//// +BlockId + +NOTE: Section pending +//// + +===== Block assignment +// tag::bl[] +In an attribute list, there are two ways to assign an id attribute to a block element. + +. Prefixing the name with a hash (`#`). +. Specifying the name with `id=`. + +[source] +---- +[#goals] +* Goal 1 +* Goal 2 +---- + +Let's say you want to create a blockquote from an open block and assign it an ID and role. +You add `quote` (the block style) in front of the `#` (the ID) in the first attribute position, as this example shows: + +[source] +---- +[quote#roads, Dr. Emmett Brown] +____ +Roads? Where we're going, we don't need roads. +____ +---- + +TIP: The order of ID and role values in the shorthand syntax does not matter. + +CAUTION: If the ID contains a `.`, you must define it using either a longhand assignment (e.g., `id=classname.propertyname`) or the anchor shorthand (e.g., `+[[classname.propertyname]]+`). +This is necessary since the `.` character in the shorthand syntax is the delimiter for a role, and thus gets misinterpreted as such. +// end::bl[] + +===== Inline assignment +// tag::in[] +The id (`#`) shorthand can be used on inline quoted text. + +.Quoted text block with id assignment using Asciidoctor shorthand +---- +[#free_the_world]*free the world* +---- +// end::in[] + +//// +.Quoted text block with `id` assignment using traditional AsciiDoc syntax +---- +[[free_the_world]]*free the world* +---- +//// diff --git a/asciidoc/_includes/attr-use.adoc b/asciidoc/_includes/attr-use.adoc new file mode 100644 index 0000000..59ad5c7 --- /dev/null +++ b/asciidoc/_includes/attr-use.adoc @@ -0,0 +1,54 @@ +//// +Included in: + +- user-manual: Using attributes: set, assign, and reference +//// + +Before you can use an attribute in your document, it must be set. +(Sometimes referred to as "`toggling on`" the attribute). + +Some attributes are automatically set when {adr} processes a document. +You can also set (or override) an attribute for a document by declaring an attribute entry. +For example: + + :sectnums: + +Many attributes can be assigned a value at the same time: + + :leveloffset: 3 + +The value may be empty, a string (of characters) or a number. +A string value may include references to other attributes. + +Attributes can be unset using the bang symbol (`!`). +The `!` can be placed either before or after the attribute's name. + +For example, both: + + :sectnums!: + +and + + :!sectnums: + +mean unset the `sectnums` attribute. +In this case, it tells Asciidoctor to not number the sections. + +To soft unset an attribute from the CLI or API, you can use the following syntax: + + !name=@ + +The leading `!` unsets the attribute while the `@` lowers the precedence of the assignment. +This assignment is almost always used to unset a default value while still allowing the document to assign a new one. +One such example is `sectids`, which is enabled by default. +`!sectids=@` switches the setting off. + +An [.term]_attribute reference_ is an inline element composed of the name of the attribute enclosed in curly brackets. +For example: + + The value of leveloffset is {leveloffset}. + +The attribute reference is replaced by the attribute's value when Asciidoctor processes the document. +Referencing an attribute that is not set is considered an error and is handled specially by the processor. + +The following sections will show you how to use attributes on your whole document, individual blocks, and inline elements. diff --git a/asciidoc/_includes/attr.adoc b/asciidoc/_includes/attr.adoc new file mode 100644 index 0000000..fb793fd --- /dev/null +++ b/asciidoc/_includes/attr.adoc @@ -0,0 +1,99 @@ +//// +Included in: + +- user-manual: Attributes +//// + +// tag::intro[] +Attributes are one of the features that sets Asciidoctor apart from other lightweight markup languages. +Attributes can activate features (behaviors, styles, integrations, etc) or hold replacement (i.e., variable) content. + +In Asciidoctor, attributes are classified as: + +* <> +* <> +* <> +* <> +* <> +* <> +// end::intro[] + +// tag::attributesyntax[] +=== Attribute Restrictions + +All attributes have a name and a value (though the value may be implicit). + +The attribute name: + +* must be at least one character long, +* must begin with a word character (A-Z, a-z, 0-9 or _) and +* must only contain word characters and hyphens. + +In other words, the name cannot contain dots or spaces. + +Although uppercase characters are permitted in an attribute entry (the place where an attribute is defined), the attribute name is converted to lowercase before being stored. +The attribute name in an attribute reference is also converted to lowercase before the attribute is resolved. +For example, `URI`, `Uri` and `uRI` are all treated as `uri`. +(See https://github.com/asciidoctor/asciidoctor/issues/509[issue #509] for a proposed change to this restriction). +A best practice is to only use lowercase for letters in the name and avoid starting the name with a number. + +The attribute value: + +* can be any inline content and +* can only contain line breaks if an explicit line continuation is used. + +Certain attributes have a restricted range of allowable values. +See the entries in the <> for details. +// end::attributesyntax[] + +=== Attribute Assignment Precedence +// tag::order[] +The attribute assignment precedence, listed from highest to lowest, is as follows: + +* An attribute defined using the API or CLI +* An attribute defined in the document +* The default value of the attribute, if applicable + +Let's use the `imagesdir` attribute to show how precedence works. + +The default value for the `imagesdir` attribute is an empty string. +Therefore, if the `imagesdir` attribute is not assigned a value (either in the document, API, or CLI), the processor will assign it the default value of empty string. +If the `imagesdir` attribute is set in the document (meaning assigned a new value, such as `images`), that value will override the default value. +Finally, if a value is assigned to the `imagesdir` attribute via the API or CLI, that value will override both the default value and the value assigned in the document. + +It's possible to alter this order of precedence using a modifier, covered in the next section. + +==== Altering the Attribute Assignment Precedence + +You can allow the document to reassign an attribute that is defined via the API or CLI by adding the `@` precedence modifier to the end of the attribute value (or, since 1.5.7, the end of the attribute name). +Adding this modifier lowers the precedence so that an assignment in the document still wins out. +We sometimes refer to this as "`soft setting`" the attribute. +This feature can be useful for assigning default values for attribute, but still letting the document control its own fate. + +NOTE: The `@` modifier is removed before the assignment is made. + +Here's an example that shows how to set the `imagesdir` from the CLI with a lower precedence: + + $ asciidoctor -a imagesdir=images@ doc.adoc + +Since 1.5.7, you can place the modifier at the end of the attribute name: + + $ asciidoctor -a imagesdir@=images doc.adoc + +It's now possible to override the value of the `imagesdir` attribute from within the document: + +[source,asciidoc] +---- += Document Title +:imagesdir: new/path/to/images +---- + +Let's update the attribute assignment precedence list defined earlier to reflect this additional rule: + +* An attribute passed to the API or CLI +* An attribute defined in the document +* An attribute passed to the API or CLI whose value (or, since 1.5.7, name) ends in `@` +* The default value of the attribute, if applicable + +Regardless of whether the precedence modifier is applied, an attribute assignment always overrides the default value. +// end::order[] diff --git a/asciidoc/_includes/attrs-builtin.adoc b/asciidoc/_includes/attrs-builtin.adoc new file mode 100644 index 0000000..c2d98d0 --- /dev/null +++ b/asciidoc/_includes/attrs-builtin.adoc @@ -0,0 +1,1035 @@ +//// +Need to update the compatibility guide with: + +* numbered = sectnums +* docinfo1 = docinfo +* docinfo2 = docinfo +* toc-class = use custom theme https://github.com/asciidoctor/asciidoctor.org/issues/379[issue #379] +* toc-placement = toc +* notitle = showtitle! +* encoding = ignored always UTF-8 + +//// +[#builtin-attributes] += Built-in Attributes +:y: icon:check[role="green"] + +Built-in document attributes can be set anywhere in the document using an attribute entry line. +However, there are some rules to keep in mind regarding the impact of that assignment. + +* Many attributes can only be defined in the <> (or via the API or CLI). +Otherwise, they won't have the desired impact. +These are called _header attributes_. +This requirement is marked in the table below. +* To set an attribute that does not accept a value, simply use an empty value (as indicated by _empty_ in the table). +* If you set an attribute from the command line or API, it's defined for the whole document and cannot be changed in the body unless `@` is added to the end of the value. +(The one exception to this rule is the `sectnums` attribute, which can always be changed). +* If you set an attribute in the body (anywhere after the document header), the attribute is visible from the point it is set until it is unset (assuming it is not locked as a result of being set from the command line or API). + +NOTE: Several attributes from AsciiDoc Python have been removed (or deprecated) in Asciidoctor and therefore are not included in this section. +See <> if you are updating an older document. + +[#builtin-attributes-table] +// tag::table[] +.Built-in document attributes +[cols="20,30,15,15,^5,15"] +|==== +|Attribute name |Description |Default value^[1]^ |Allowed values |Header only |See also + +6+> + +|attribute-undefined +|Controls how expressions that undefine an attribute are handled. +|drop-line +|drop or drop-line +| +|<> + +|compat-mode +|Controls whether the legacy parser is used to parse the document. +|_not set_ (Modern parser is used). +|_empty_ (Legacy parser is used). +| +|<> + +|experimental +|Enable experimental extensions. +The features behind this attribute are subject to change and may even be removed in a future version. +Currently enables the UI macros (button, menu and kbd). +|_not set_ +|_empty_ +|{y} +|<> + +|reproducible +|If set, prevents the last-updated date from being added to the HTML footer or DocBook info element. +Alternatively, you can use the SOURCE_DATE_EPOCH environment variable to fix the value. +Useful if you want to store the output in a source code control system as it prevents spurious changes every time you convert the document. +|_not set_ +|_empty_ +|{y} +| + +6+>, <> + +|appendix-number +|Stores the number (aka letter) for the current appendix.^[<>]^ +|A +|_letter_ +| +| + +|appendix-refsig +|Sets the signifier added to the title of appendices in cross reference text. +Unset to disable. +|Appendix +|_any_ +| +|<>, <>, <> + +|caution-caption +|Sets the text used to label CAUTION admonitions when icons are not enabled. +|Caution +|_any_ +| +|<>, <> + +|chapter-number +|Stores the number for the current chapter.^[<>]^ +|2 +|_integer_ +| +| + +|chapter-refsig +|Sets the signifier added to the title of numbered chapters in cross reference text. +Unset to disable. +|Chapter +|_any_ +| +|<>, <>, <> + +|chapter-label +|Sets the prefix added to chapter titles (i.e., level-1 section titles when doctype is book). +_(pdf converter only)_ +|Chapter +|_any_ +| +|<>, <>, <> + +|example-caption +|Sets the text used to label example blocks. +|Example +|_any_ +| +|<> + +|example-number +|Stores the number for the current numbered example.^[<>]^ +|5 +|_integer_ +| +| + +|figure-caption +|Sets the text used to label figures. +|Figure +|_any_ +| +|<>, <> + +|figure-number +|Stores the number for the current numbered figure.^[<>]^ +|3 +|_integer_ +| +| + +|important-caption +|Sets the text used to label IMPORTANT admonitions when icons are not enabled. +|Important +|_any_ +| +|<>, <> + +|lang +|Set the value of the `lang` attribute on the root element of the output document. +|en +|Valid XML country code +|{y} +|<> + +|last-update-label +|Text label for the “Last updated” time in the footer. +Unsetting it will remove the label and time from the footer. +|Last updated +|_any_ +|{y} +|<>, <> + +|listing-caption +|Sets the text used to label listing blocks. +|_not set_ +|_any_ +| +|<> + +|listing-number +|Stores the number for the current numbered listing.^[<>]^ +|5 +|_integer_ +| +| + +|manname-title +|Label for the program name section in the man page. +|NAME +|_any_ +|{y} +|<> + +|nolang +|Prevents the `lang` attribute from being added to root element of the output document. +|_not set_ +|_empty_ +|{y} +| + +|note-caption +|Sets the text used to label NOTE admonitions when icons are not enabled. +|Note +|_any_ +| +|<>, <> + +|preface-title +|Sets the title text for an anonymous preface when the doctype is book. +|_not set_ +|_any_ +| +|<> + +|section-refsig +|Sets the signifier added to the title of numbered sections in cross reference text. +Unset to disable. +|Section +|_any_ +| +|<>, <>, <> + +|table-caption +|Text of the label that is automatically prefixed to table titles. +To turn off table caption labels and numbers, add the `table-caption` attribute to the document header with an empty value. +|Table +|_any_ +| +|<> + +|table-number +|Stores the number for the current numbered table.^[<>]^ +|5 +|_integer_ +| +| + +|tip-caption +|Sets the text used to label TIP admonitions when icons are not enabled. +|Tip +|_any_ +| +|<>, <> + +|toc-title +|Title for the table of contents. +|Table of Contents +|_any_ +| +|<>, <> + +|untitled-label +|Used as the default document title if the document does not have a document title. +|Untitled +|_any_ +|{y} +|<> + +|version-label +|The label preceding the revnumber in a converted document's byline +|Version +|_any_ +|{y} +|<>, <> + +|warning-caption +|Sets the text used to label TIP admonitions when icons are not enabled. +|Warning +|_any_ +| +|<> + +6+> + +|authorinitials +|Sets the author's initials (e.g., JD). +Derived automatically from the author attribute by default. +|_not set_ +|_any_ +|{y} +|<> + +|authors +|Sets the document authors as a comma-separated list. +Can be set automatically via the author info line. +If set, adds an `author` meta element inside the HTML document head. +|_not set_ +|_any_ +|{y} +|<> + +|copyright +|If set, adds a `copyright` meta element inside the HTML document head. +|_not set_ +|_any_ +|{y} +|<> + +|doctitle +|Sets the document title. +Set automatically to section title if document begins with level-0 section. +|Based on content. +|_any_ +|{y} +|<> + +|description +|If set, adds a `description` meta element inside the HTML document head. +|_not set_ +|_any_ +|{y} +|<> + +|email +|Sets the author's email address. +Can be set automatically via the author info line. +Can be any inline macro, such as a URL. +|_not set_ +|_any_ +|{y} +|<> + +|favicon +|Adds a link to a favicon to the HTML ``. +|_not set_ +|_any_ +|{y} +|<> + +|firstname +|Sets the author's first name. +Can be set automatically via the author info line. +|_not set_ +|_any_ +|{y} +|<> + +|front-matter +|If `skip-front-matter` is set via the CLI or API, any YAML-style frontmatter skimmed from the top of the document is stored in this attribute. +|Front matter content, if captured. +|_any_ +|{y} +|<> + +|keywords +|If set, adds a `keywords` meta element inside the HTML document head. +|_not set_ +|_any_ +|{y} +|<> + +|lastname +|Sets the author's last name. +Can be set automatically via the author info line. +|_not set_ +|_any_ +|{y} +|<> + +|middlename +|Sets the author's middle name or initial. +Can be set automatically via the author info line. +|_not set_ +|_any_ +|{y} +|<> + +|orgname +|If set, add an `` element with this value to the DocBook info element. +|_not set_ +|_any_ +|{y} +|<> + +|revdate +|Sets the revision date. +Can be set automatically via the revision info line. +|_not set_ +|_any_ +|{y} +|<> + +|revremark +|Sets the revision description. +Can be set automatically via the revision info line. +|_not set_ +|_any_ +|{y} +|<> + +|revnumber +|Sets the revision number. +Can be set automatically via the revision info line. +|_not set_ +|_any_ +|{y} +|<> + +|title +|Sets the value of the `` element in the HTML `<head>` or main DocBook `<info>` of the output document. +Also used as a fallback when the document title is not specified. +_Since this is a reserved attribute that has special behavior, you should avoid using it for any other purpose!_ +|_not set_ +|_any_ +|{y} +|<<document-title>> + +6+<h|Section titles and table of contents + +|idprefix +|Sets prefix used for auto-generated section IDs. +|_ +|Valid XML ID start character. +|{y} +|<<auto-generated-ids>> + +|idseparator +|Sets word separator used in auto-generated section IDs. +|_ +|Valid XML ID character. +|{y} +|<<auto-generated-ids>> + +|leveloffset +|Pushes the level of subsequent headings down, to make file inclusion more useful. +|0 +|(+/-)0{endash}5. (A leading + or - makes it relative). +| +|<<include-partitioning>> + +|sectanchors +|If set, adds an anchor in front of the section title when the mouse cursor hovers over it. +|_not set_ (No anchors). +|_empty_ +|{y} +|<<anchors>> + +|sectids +|If set, generates and assigns an ID to any section that does not have one. +|_empty_ (Assigns section ID if not specified). +|_empty_ +|{y} +|<<auto-generated-ids>> + +|sectlinks +|Turns section titles into self-referencing links. +|_not set_ +|_empty_ +|{y} +|<<links>> + +|sectnums +|If set, numbers sections to depth specified by sectnumlevels. +|_not set_ (Sections are not numbered). +|_empty_ +|{y} +|<<numbering>> + +|sectnumlevels +|controls the depth of section numbering +|3 +|0{endash}5 +|{y} +|<<numbering-depth>> + +|title-separator +|The character used to separate the main title and subtitle in the document title. +|: +|_any_ +|{y} +|<<subtitle-partitioning>> + +|toc +|Switches the table of contents on, and defines its location. +|_not set_ +|auto, left, right, macro or preamble +|{y} +|<<user-toc>> + +|toclevels +|Maximum section level to display. +|2 +|1{endash}5 +|{y} +|<<user-toc>> + +// NOTE toc-placement moved to deprecated table in migration guide +//|toc-placement +//|Location where table of contents is inserted. +//Should be treated as read-only. +//|Based on value of `toc` attribute. +//|auto, preamble, macro +//|{y} +//|<<user-toc>> + +|fragment +|Hints to parser that document is a fragment and it should not enforce proper section nesting. +|_not set_ +|_empty_ +| +| + +6+<h|General content and formatting + +|asset-uri-scheme +|Controls which protocol is used for assets hosted on a CDN. +|https +|_empty_, http or https +|{y} +| + +|cache-uri +|If set, cache content read from URIs. +|_not set_ +|_empty_ +|{y} +|<<caching-uri-content>> + +|data-uri +|Embed graphics as data-uri elements in HTML elements so the file is completely self-contained. +|_not set_ (Images are linked, not embedded). +|_empty_ +|{y} +|<<managing-images>> + +|docinfo +|Read input from one or more DocBook info files. +|_not set_ +|Comma-separated list of the following values: shared, private, shared-head, private-head, shared-footer or private-footer +|{y} +|<<naming-docinfo-files>> + +|docinfodir +|The location where docinfo files are resolved. +|The base directory. +|Directory +|{y} +|<<locating-docinfo-files>> + +|docinfosubs +|The AsciiDoc substitutions that get applied to docinfo content. +|attributes +|Comma-separated list of substitution names. Set value to empty or `none` to disable substitutions. +|{y} +|<<attribute-substitution-in-docinfo-files>> + +|doctype +|Set the output document type. +|article +|article, book, inline or manpage +|{y} +|<<document-types>> + +|eqnums +|Controls automatic equation numbering on LaTeX blocks in HTML output (MathJax). +If the value is AMS, only LaTeX content enclosed in an `\begin{equation}\...\end{equation}` container will be numbered. +If the value is all, then all LaTeX blocks will be numbered. +|_not set_ (Equation numbering is off) +|_empty_ (alias for AMS), AMS, all or none +|{y} +|<<stem>>, https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numbering[Equation numbering in MathJax] + +|hardbreaks +|Preserve hard line breaks in the input. +|_not set_ +|_empty_ +| +|<<line-breaks>> + +|hide-uri-scheme +|Hides the URI scheme for all raw links. +|_not set_ +|_empty_ +| +|<<url>> + +|linkattrs +|Parse attributes inside the link macro. +Removed in Asciidoctor 1.5.7. +Attributes are now parsed automatically if an equal sign is found after a comma (e.g., `[link text,window=_blank]`). +|_not set_ (Do not parse). +|_empty_ +| +|<<url>> + +|media +|Specifies the media type of the output, which may enable behavior specific to that media type. +|_screen_ +|screen or print +|{y} +| + +|nofooter +|Suppresses output of the footer. +|_not set_ +|_empty_ +|{y} +|<<footer-docinfo-files>> + +|nofootnotes +|Turn off display of footnotes. +|_not set_ +|_empty_ +|{y} +|<<user-footnotes>> + +|noheader +|Suppresses output of the header. +|_not set_ +|_empty_ +|{y} +|<<doc-header>> + +|outfilesuffix +|File extension of the output file (starting with a period). +|Determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc). +|File extension +| +|<<navigating-between-source-files>> + +|pagewidth +|Page width, used to calculate the absolute width of tables in the DocBook output. +|425 +|Number +|{y} +| + +|relfileprefix +|The path prefix to add to relative xrefs. +|_empty_ +|Path segment +| +|<<navigating-between-source-files>> + +|show-link-uri +|Prints the URI of a link after the linked text. + _(pdf converter only)_ +|_not set_ +|_empty_ +|{y} +| + +|showtitle +|If set, displays an embedded document's title. +Mutually exclusive with the `notitle` attribute. +|_not set_ +|_empty_ +|{y} +|<<document-title>> + +|stem +|Enables mathematics processing or sets the processor used. +|_not set_ +|_empty_ (defaults to asciimath), asciimath or latexmath +|{y} +|<<stem-in>> + +|tabsize +|If set, converts tabs to spaces in verbatim content blocks (e.g., listing, literal). +|_not set_ +|0 or more +| +|- + +|webfonts +|Control whether webfonts are loaded, and which ones, when using the default stylesheet. +The value populates the `family` query string parameter in the Google Fonts URL. +|_empty_ (use default fonts) +|_empty_ or a Google Fonts collection spec +|{y} +|<<applying-a-theme>> and https://github.com/asciidoctor/asciidoctor.org/issues/410[issue #410] + +|xmlns +|The XML namespace to add to the DocBook 4.5 document. (The DocBook 5 document always declares a namespace). +|_not set_ +|_empty_ (alias for the DocBook namespace) or a valid XML namespace. +|{y} +|<<docbook>> + +|xrefstyle +|The formatting style to apply to cross reference text. +_Introduced in 1.5.6._ +|_not set_ +|full, short, or basic +|{y} +|<<customizing-the-cross-reference-text>> + +6+<h|Images and icons + +|iconfont-cdn +|Overrides the CDN used to resolve the Font Awesome stylesheet. +Only used when `icons` attribute is set to `font`. +|cdnjs +|URI +|{y} +|<<icons>> + +|iconfont-name +|Overrides the name of the icon font stylesheet. +Only used when `icons` attribute is set to `font`. +|font-awesome +|_any_ +|{y} +|<<icons>> + +|iconfont-remote +|If set, allows use of a CDN for resolving the icon font. +Only used when `icons` attribute is set to `font`. +|_empty_ +|_empty_ +|{y} +|<<icons>> + +|icons +|Chooses icons instead of text for admonitions. +|_not set_ (image) +|font or image +|{y} +|<<icons>> + +|iconsdir +|Where icons are stored. +Only used when `icons` attribute is set to `image`. +|\{imagesdir}/icons (or ./images/icons if imagesdir is not set) +|Directory +|{y} +|<<icons>> + +|icontype +|File type for image icons. +Only used when `icons` attribute is set to `image`. +|png +|any, but typically jpg, tiff, etc. +|{y} +|<<icons>> + +|imagesdir +|Where image files are resolved. +|_not set_ (Same directory as document). +|Directory +| +|<<images>> + +6+<h|Code highlighting and formatting + +|coderay-css +|Controls whether CodeRay uses CSS classes or inline styles. +|class +|class or style +|{y} +|<<coderay>> + +|coderay-linenums-mode +|Sets how CodeRay inserts line numbers into source listings. +|table +|table or inline +|{y} +|<<coderay>> + +|coderay-unavailable +|If set, tells the processor not to attempt to load CodeRay. +|_not set_ +|_empty_ +|{y} +|<<coderay>> + +|highlightjsdir +|Location of the highlight.js source code highlighter library. +|_not set_ +|Directory +|{y} +|<<highlight-js>> + +|highlightjs-theme +|Sets the name of the theme used by the highlight.js source code highlighter. +|github +|A style name recognized by highlight.js. +|{y} +|<<highlight-js>> + +|prettifydir +|Location of the prettify source code highlighter library. +|_not set_ (Uses CDN). +|Directory +|{y} +|<<source-code-blocks>> + +|prettify-theme +|Sets the name of the theme used by the prettify source code highlighter. +|prettify +|A style name recognized by prettify. +|{y} +|<<source-code-blocks>> + +|prewrap +|Wrap wide code listings. +Sets the default behavior only; you can still switch off wrapping on specific listings. +|_empty_ (Code listing will wrap long lines, not scroll). +|_empty_ +| +|<<to-wrap-or-to-scroll>> + +|pygments-css +|Controls whether Pygments uses CSS classes or inline styles. +|class +|class or style +|{y} +|<<pygments>> + +|pygments-linenums-mode +|Sets how Pygments inserts line numbers into source listings. +|table +|table or inline +|{y} +|<<pygments>> + +|pygments-style +|Sets the name of the style used by the Pygments source code highlighter +|default +|A style name recognized by Pygments. +|{y} +|<<pygments>> + +|pygments-unavailable +|If set, tells the processor not to attempt to load Pygments. +|_not set_ +|_empty_ +|{y} +|<<pygments>> + +|source-highlighter +|Source code highlighter to use. +|_not set_ +|coderay, highlightjs, prettify or pygments +|{y} +|<<source-code-blocks>> + +|source-indent +|Normalize block indentation in code listings. +|_not set_ (Indentation is not modified). +|Number +| +|<<normalize-block-indentation>> + +|source-language +|Set the default language for source code listings. +|_not set_ +|Code language name in lowercase. +| +|<<source-code-blocks>> + +|source-linenums-option +|Turns on line numbers option by default for source code listings. +_Introduced in 1.5.6._ +|_not set_ +|_empty_ +| +|<<source-code-blocks>> + +6+<h|HTML styling + +|copycss +|If set, copy the CSS files to the output. +|_empty_ (File is copied if `linkcss` is set). +|Empty or the location of the custom stylesheet (if used) +|{y} +|<<applying-a-theme>> + +|css-signature +|If set, assign the value to the `id` attribute of the `<body>` element (HTML only). +The preferred approach is to assign an ID to the document title. +|_not set_ +|Valid XML ID +|{y} +// TODO link to <<document-title>> once it covers ID assignment +| + +|linkcss +|If set, link to the stylesheet instead of embedding it. +Cannot be unset in SECURE safe mode. +|_not set_ (when safe mode < SECURE) + +_set_ (when safe mode is SECURE) +|_empty_ +|{y} +|<<styling-the-html-with-css>> + +|max-width +|Constrain the maximum width of the document body. +*Not recommended. +Use custom CSS instead.* +|_not set_ +|CSS length (e.g. 55em, 12cm, etc) +|{y} +| + +|stylesdir +|Location for resolving CSS stylesheets. +|. (Same directory as document). +|Directory +|{y} +|<<creating-a-theme>> + +|stylesheet +|Name of a CSS stylesheet to replace the default one. +|_not set_ (The default stylesheet is used). +|File name +|{y} +|<<applying-a-theme>> + +|toc-class +|The CSS class on the table of contents container. +|toc +|Valid CSS class name +|{y} +|<<user-toc>> + +6+<h|Manpage attributes (relevant only when using the manpage doctype and/or converter) + +|mantitle +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<<man-pages>> + +|manvolnum +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<<man-pages>> + +|manname +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<<man-pages>> + +|manpurpose +|Metadata for manpage output. +|Based on content. +|_any_ +|{y} +|<<man-pages>> + +|man-linkstyle +|Style the links in the manpage output. +|blue R <> +|Link format sequence +|{y} +|<<man-pages>> + +|mansource +|The source (e.g., application and version) to which the man page pertains. +|_not set_ +|_any_ +|{y} +|<<man-pages>> + +|manmanual +|Manual name displayed in the man page footer. +|_not set_ +|_any_ +|{y} +|<<man-pages>> + +6+<h|Secure attributes (can only be set from the command line or API, typically for security reasons) + +|allow-uri-read +|If set, allows data to be read from URIs (via include directive, image macro when embedding images, etc.). +|_not set_ +|_empty_ +|CLI or API +|<<include-uri>> + +|max-attribute-value-size +|Limits the maximum size (in bytes) of a resolved attribute value. +Since attributes can reference other attributes, it would be possible to create an output document disproportionately larger than the input document without this limit in place. +|4096 (secure mode), _not set_ (other modes) +|0 or greater +|CLI or API +| + +|max-include-depth +|Safety feature to curtail infinite include loops and to limit the opportunity to exploit nested includes to compound the size of the output document. +|64 +|0 or greater +|CLI or API +|<<include-directive>> + +|skip-front-matter +|If set, consume YAML-style frontmatter at the top of the document and store it in the `front-matter` attribute. +|_not set_ +|_empty_ +|CLI or API +|<<front-matter-added-for-static-site-generators>> +|==== + +^[1]^ The default value isn't necessarily the value you will get by entering `\{name}`. +It may be the fallback value which Asciidoctor uses if the attribute is not defined. +The effect is the same either way. + +[[note_blocknum]]^[2]^ The `-number` attributes are created and managed automatically by Asciidoctor for numbered blocks. +They are only used if the corresponding `-caption` attribute is set (e.g., `listing-caption`) and the block has a title. +In the current version of Asciidoctor, setting the `-number` attributes will influence the number used for subsequent numbered blocks of that type. +However, you should not rely on this behavior as it may change in future versions. +// end::table[] diff --git a/asciidoc/_includes/attrs-charref.adoc b/asciidoc/_includes/attrs-charref.adoc new file mode 100644 index 0000000..cd08581 --- /dev/null +++ b/asciidoc/_includes/attrs-charref.adoc @@ -0,0 +1,144 @@ +[#charref-attributes] += Predefined Attributes for Character Replacements + +[#charref-attributes-table] +// tag::table[] +.Predefined attributes for character replacements ^[1][2][3]^ +[width="75%", cols="^4m,^3l,^3"] +|=== +|Attribute name |Replacement text |Appearance + +|blank +e|nothing +|{empty} + +|empty +e|nothing +|{empty} + +|sp +e|single space +|{sp} + +|nbsp +|  +|{nbsp} + +|zwsp^[4]^ +|​ +|{zwsp} + +|wj^[5]^ +|⁠ +|{wj} + +|apos +|' +|{apos} + +|quot +|" +|{quot} + +|lsquo +|‘ +|{lsquo} + +|rsquo +|’ +|{rsquo} + +|ldquo +|“ +|{ldquo} + +|rdquo +|” +|{rdquo} + +|deg +|° +|{deg} + +|plus +|+ +|{plus} + +|brvbar +|¦ +|¦ + +|vbar +|\| +|{vbar} + +|amp +|& +|& + +|lt +|< +|< + +|gt +|> +|> + +|startsb +|[ +|[ + +|endsb +|] +|] + +|caret +|^ +|^ + +|asterisk +|* +|* + +|tilde +|~ +|~ + +|backslash +|\ +|\ + +|backtick +|` +|` + +|two-colons +|:: +|:: + +|two-semicolons +|;; +|;; + +|cpp +|C++ +|C++ +|=== + +^[1]^ Some replacements are Unicode characters, whereas others are numeric character references (e.g., \"). +These character references are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser). +It's up to the converter to transform the reference into something the renderer understands (something both the man page and PDF converter handle). + +^[2]^ Asciidoctor does not prevent you from reassigning predefined attributes. +However, it's best to treat them as read-only unless the output format requires the use of a different encoding scheme. +These attributes are an effective tool for decoupling content and presentation. + +^[3]^ Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., \€ resolves to €). +However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. +Our recommendation is avoid using named character references--with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). +Instead, use numeric character references (e.g., \€). + +^[4]^ The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary. + +^[5]^ The word joiner (WJ) is a code point in Unicode that prevents a line break at its position. +// end::table[] diff --git a/asciidoc/_includes/attrs-env.adoc b/asciidoc/_includes/attrs-env.adoc new file mode 100644 index 0000000..4cb2ed1 --- /dev/null +++ b/asciidoc/_includes/attrs-env.adoc @@ -0,0 +1,156 @@ +//// +Included in: + +- user-manual appendix B attribute calatog +//// +[#env-attributes] += Environment Attributes + +Asciidoctor automatically assigns values to various document attributes whenever a document is loaded or converted. +These attributes, termed [.term]_environment attributes_, provide information about the runtime environment, such as how, where and when the document is being processed. +Like other document attributes, environment attributes can be referenced whereever attribute references are permitted. +It's recommended that you treat these attributes as read only. + +[#env-attributes-table] +// tag::table[] +.Environment attributes +[cols="1m,2,1m"] +|=== +|Attribute |Description |Example Value + +|asciidoctor +|Set if the current processor is Asciidoctor. +|{asciidoctor} + +|asciidoctor-version +|Asciidoctor version. +|{asciidoctor-version} + +|backend +|Backend used to create the output file. +|html5 + +|basebackend +|The backend value minus any trailing numbers. +For example, if the backend is `docbook5`, the basebackend is `docbook`. +|html + +|docdate +|Last modified date of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ +|2019-01-04 + +|docdatetime +|Last modified date and time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ +|2019-01-04 19:26:06 UTC + +|docdir +|Full path of the directory that contains the source document. +|/home/user/docs + +|docfile +|Full path of the source document. +|/home/user/docs/userguide.adoc + +|docfilesuffix +|File extension of the source document, including the leading period. +_Introduced in 1.5.6._ +|.adoc + +|docname +|Root name of the source document (no leading path or file extension). +|userguide + +|doctime +|Last modified time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ +|19:26:06 UTC + +|doctype +|Document type (article, book or manpage). +|article + +|docyear +|Year that the document was last modified.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ +|2018 + +|embedded +|Set if content is being converted to an embeddable document (body only). +| + +|filetype +|File extension of the output file name (without leading period). +|html + +|htmlsyntax +|Syntax used when generating the HTML output (html or xhtml). +|html + +|localdate +|Date when the document was converted.^[<<note_sourcedateepoch,2>>]^ +|2019-02-17 + +|localdatetime +|Date and time when the document was converted.^[<<note_sourcedateepoch,2>>]^ +|2019-02-17 19:31:05 UTC + +|localtime +|Time when the document was converted.^[<<note_sourcedateepoch,2>>]^ +|19:31:05 UTC + +|localyear +|Year when the document was converted.^[<<note_sourcedateepoch,2>>]^ +|2018 + +|outdir +|Full path of the output directory. +|/home/user/docs/dist + +|outfile +|Full path of the output file. +|/home/user/docs/dist/userguide.html + +|outfilesuffix +|File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.). +(The value is not updated to match the file extension of the output file when one is specified explicitly). +_Safe to modify._ +|.html + +|safe-mode-level +|Numeric value of the safe mode setting. +(UNSAFE=0, SAFE=10, SERVER=10, SECURE=20). +|20 + +|safe-mode-name +|Textual value of the safe mode setting. +|SERVER + +|safe-mode-unsafe +|Set if the safe mode is UNSAFE. +| + +|safe-mode-safe +|Set if the safe mode is SAFE. +| + +|safe-mode-server +|Set if the safe mode is SERVER. +| + +|safe-mode-secure +|Set if the safe mode is SECURE. +| + +|user-home +|Home directory of the current user. +Resolves to `.` if the safe mode is SERVER or greater. +|/home/user +|=== + +[[note_docdatetime]]^[1]^ Only reflects the last modified time of the source document file. +It does not consider the last modified time of files which are included. + +[[note_sourcedateepoch]]^[2]^ If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable. +This override offers one way to make the conversion reproducible. +See https://reproducible-builds.org/specs/source-date-epoch/ for more information about the SOURCE_DATE_EPOCH environment variable. +Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., `-0600`) or UTC if the time zone offset is 0). +To force the use of UTC, set the `TZ=UTC` environment variable when invoking Asciidoctor. +// end::table[] diff --git a/asciidoc/_includes/author.adoc b/asciidoc/_includes/author.adoc new file mode 100644 index 0000000..77dff08 --- /dev/null +++ b/asciidoc/_includes/author.adoc @@ -0,0 +1,118 @@ +//// +Included in: + +- user-manual: Header +//// + +The author of a document is listed on the line beneath the document's title. +An optional email address or URL can follow an author's name inside angle brackets. + +Let's add an author with her email address to the document below. + +[source] +---- +include::ex-author.adoc[tag=base] +---- + +.Result: Rendered author and email information displayed on the byline and referenced in the document's body +==== +image::author-email.png[Author and email attributes] +==== + +As you can see in the example above, Asciidoctor uses the author's name and email to assign values to a number of built-in attributes that can be used throughout the document's body. +These attributes include: + +`author`:: +The author's full name, which includes all of the characters or words prior to a semicolon (`;`), angle bracket (`<`) or the end of the line. + +`firstname`:: +The first word in the author attribute. + +`lastname`:: +The last word in the author attribute. + +`middlename`:: +If a firstname and lastname are present, any remaining words or characters found between these attributes are assigned to the middlename attribute. + +`authorinitials`:: +The first character of the firstname, middlename, and lastname attributes. + +`email`:: +An email address, delimited by angle brackets (`<>`). + +If one or more of the author's names consists of more than one word, use an underscore (`_`) between the words you want to adjoin. +For example, the author of the following document has a compound last name. + +[source] +---- +include::ex-author.adoc[tag=2-mid] +---- + +.Result: Rendered author information when author has a compound name +==== +image::author-compound.png[Compound author name attributes] +==== + +Alternatively, the author and email attributes can be set explicitly in the header. + +[source] +---- +include::ex-author.adoc[tag=attr] +---- + +.Result: Rendered author information when author and email attributes are explicitly set +==== +image::author-email-long.png[Author and email attributes] +==== + +The `html5` and `docbook` converters can convert documents with multiple authors. +Multiple authors and their emails are separated by semicolons (`;`) when they're listed on the same line. + +[source] +---- +include::ex-author.adoc[tag=multi] +---- +<1> To reference the additional authors in the document body, the author attributes are appended with an underscore (`+_+`) followed by the position of the author in the author information list (i.e. Lazarus het Draeke is the second author in the list so his author attributes are appended with a 2). + +.Result: Rendered author information when document has multiple authors +==== +image::multi-author.png[Multiple author and email attributes] +==== + +//// +If you want to enter multiple authors and their emails as attribute entries, the attribute names are as follows: + +[source] +---- +include::multi-author-email-long.adoc[] +---- + +.Result +==== +image::multi-author-email-long.png[Multiple author and email attributes] +==== + +Where does `authored` (empty string '' if {author} or {email} defined) fit in? +//// + +==== Attribute references in the author line + +The implicit author line was not intended to support arbitrary placement of attribute references. +While attribute references are replaced in the author line (as part of the header substitution group), they aren't substituted until _after_ the line is parsed. +This ordering can sometimes produce undesirable or surprising results. +It's best to use the author line strictly as a shorthand for defining a fixed author and email. + +If you do need to use attribute references in the author or email value, you should revert to defining the attributes explicitly using attribute entries. + +.Using attribute references to set author and email +[source] +---- += Document Title +:author_name: ACME Industries +:author_email: info@acme.com +:author: {author_name} +:email: {author_email} +---- + +Just remember that the author line is for static text. +Once you graduate beyond static text, you should switch to using attribute entries to define the built-in author attributes, which will give you much more power. diff --git a/asciidoc/_includes/benefits.adoc b/asciidoc/_includes/benefits.adoc new file mode 100644 index 0000000..8cafdcd --- /dev/null +++ b/asciidoc/_includes/benefits.adoc @@ -0,0 +1,68 @@ +//// +Included in: + +- user-manual: Asciidoctor's most notable benefits + +The primary benefits and supporting features of the application. +//// + +While Asciidoctor aims to offer full compliance with the AsciiDoc syntax, it's more than just a clone. + +.Built-in and custom templates +Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook output that is structurally equivalent to what AsciiDoc produces. +Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem. +Custom template rendering is handled by the {uri-tilt}[Tilt] template abstraction library. +Tilt is one of the most popular gems in the Ruby ecosystem. + +.Parser and object model +Leveraging the Ruby stack isn't the only benefit of Asciidoctor. +Unlike the AsciiDoc Python implementation, Asciidoctor parses and converts the source document in discrete steps. +This makes conversion optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles. +Developers can use the full power of the Ruby programming language to play with the content in the document. + +.Performance and security +No coverage of Asciidoctor would be complete without mention of its _speed_. +Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. +It loads, parses, and converts documents a *100 times as fast* as the Python implementation. +That's good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. +Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments. + +.Beyond Ruby +Asciidoctor's usage is not limited to the Ruby community. +Thanks to {uri-jruby}[JRuby], a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well. +Plugins are available for {uri-org}/asciidoctor-maven-plugin[Apache Maven], {uri-org}/asciidoctor-gradle-plugin[Gradle], and {uri-rewrite}[Rewrite]. +These plugins are based on the {uri-asciidoctorj}[AsciidoctorJ] for Asciidoctor. + +Asciidoctor also ships with a command line interface (CLI). +The Asciidoctor CLI, {uri-man}[asciidoctor], is a drop-in replacement for the `asciidoc.py` script from the AsciiDoc Python distribution. + +//// + +AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets. +In other words, it's about discovering _writing zen_. + +AsciiDoc works because: + +- It's readable +- It's concise +- It's comprehensive +- It's extensible +- It produces beautiful output (HTML, DocBook, PDF, ePub and more) + +AsciiDoc is both easy to write and easy to read (in raw form). +It's also easy to proof and edit. +After all, it's plain text, just like that familiar e-mail. + +The AsciiDoc syntax is intuitive because it recognizes time-tested, plain text conventions for marking up or structuring the text. +The punctuation was carefully chosen to look like what it means. +A user unfamiliar with AsciiDoc can figure out the structure and semantics (i.e., what you mean) just by looking at it. +Best of all, *it only requires a text editor to read or write*. + +AsciiDoc allows you to focus on the actual writing and only worry about tweaking the output when you are ready to render the document. +The plain-text of an AsciiDoc document is easily converted into a variety of output formats, beautifully formatted, without having to rewrite the content. + +Copy text from an e-mail into a document and see how quickly you can turn it into documentation. +Almost immediately, you'll find your writing zen and enjoy the rewarding experience of sharing knowledge. + +Live or die by documentation? Live. +//// diff --git a/asciidoc/_includes/biblio.adoc b/asciidoc/_includes/biblio.adoc new file mode 100644 index 0000000..f011938 --- /dev/null +++ b/asciidoc/_includes/biblio.adoc @@ -0,0 +1,48 @@ +//// +Included in: + +- user-manual: Bibliography +//// + +AsciiDoc has basic support for bibliographies. +AsciiDoc doesn't concern itself with the structure of the bibliography entry itself, which is entirely freeform. +What it does is provide a way to make references to the entries from the same document and output the bibliography with proper semantics for processing by other toolchains (such as DocBook). + +In order to reference a bibliography entry, you need to assign a _non-numeric_ label to the entry. +To assign this label, prefix the entry with the label enclosed in a pair of triple square brackets (e.g., `+[[[label]]]+`). +We call this a bibliography anchor. +Using this label, you can then reference the entry from anywhere above the bibliography in the same document using the normal cross reference syntax (e.g., `+<<label>>+`). + +By default, the bibliography anchor and reference to the bibliography entry is converted to `[<label>]`, where <label> is the ID of the entry. +If you specify xreftext on the bibliography anchor (e.g., `+[[[label,xreftext]]]+`), the bibliography anchor and reference to the bibliography entry converts to `[<xreftext>]` instead. + +If you want the bibliography anchor and reference to appear as a number, assign the number of the entry using the xreftext. +For example, `+[[[label,1]]]+` will be converted to `[1]`. + +The bibliography entries themselves are declared as items in an unordered list. +You promote a normal unordered list to a bibliography list by adding the `bibliography` style. +However, to be conforming, bibliography lists must be contained inside a bibliography section. +A bibliography section is a section with the special `bibliography` style. +By adding the `bibliography` style to the section, you implicitly add it to each unordered list in that section. + +WARNING: If the bibliography style is used on an unordered list outside of a bibliography section, the resulting behavior is undefined. + +Let's consider an example. + +.Bibliography with inbound references +[source] +---- +include::ex-biblio.adoc[tag=base] +---- + +This renders as: + +|=== +a| +include::ex-biblio.adoc[tag=base] +|=== + +If you want more advanced features such as automatic numbering and custom citation styles, try the {uri-org}/asciidoctor-bibtex[asciidoctor-bibtex] project. + +TIP: To escape a bibliography anchor anywhere in the text, use the syntax `[\[[word]]]`. +This prevents the anchor from being matched as a bibliography anchor or a normal anchor. diff --git a/asciidoc/_includes/block-name-table.adoc b/asciidoc/_includes/block-name-table.adoc new file mode 100644 index 0000000..cdda116 --- /dev/null +++ b/asciidoc/_includes/block-name-table.adoc @@ -0,0 +1,94 @@ +//// +Table of blocks, block names, block delimiters, and their substitutions + +User Manual: Blocks +//// + +[cols="1,1m,1m,3,1"] +|=== +|Block |Block Name |Delimiter |Purpose |Substitutions + +|Admonition +|++[<LABEL>]++ +|++====++ +|Aside content that demands special attention; often labeled with a tag or icon +|Normal + +|Comment +d|N/A +|++////++ +|Private notes that are not displayed in the output +|None + +|Example +|++[example]++ +|++====++ +|Designates example content or defines an admonition block +|Normal + +|Fenced +d|N/A +|++```++ +|Source code or keyboard input is displayed as entered +|Verbatim + +|Listing +|++[listing]++ +|++----++ +|Source code or keyboard input is displayed as entered +|Verbatim + +|Literal +|++[literal]++ +|++....++ +|Output text is displayed exactly as entered +|Verbatim + +|Open +d|Most block names +|++--++ +|Anonymous block that can act as any block except _passthrough_ or _table_ blocks +|Varies + +|Passthrough +|++[pass]++ +|pass:[++++] +|Unprocessed content that is sent directly to the output +|None + +|Quote +|++[quote]++ +|++____++ +|A quotation with optional attribution +|Normal + +|Sidebar +|++[sidebar]++ +|++****++ +|Aside text and content displayed outside the flow of the document +|Normal + +|Source +|++[source]++ +|++----++ +|Source code or keyboard input to be displayed as entered +|Verbatim + +|Stem +|++[stem]++ +|pass:[++++] +|Unprocessed content that is sent directly to an interpreter (such as AsciiMath or LaTeX math) +|None + +|Table +d|N/A +|++\|===++ +|Displays tabular content +|Varies + +|Verse +|++[verse]++ +|++____++ +|A verse with optional attribution +|Normal +|=== diff --git a/asciidoc/_includes/block.adoc b/asciidoc/_includes/block.adoc new file mode 100644 index 0000000..a3deed6 --- /dev/null +++ b/asciidoc/_includes/block.adoc @@ -0,0 +1,151 @@ +//// +General Block Documentation + +User manual: Blocks +//// + +NOTE: Section Pending + +=== Title + +You can assign a title to any paragraph, list, delimited block, or block macro. +In most cases, the title is displayed immediately above the content. +If the content is a figure or image, the title is displayed below the content. + +A block title is defined on a line above the element. +The line must begin with a dot (`.`) and be followed immediately by the title text. + +Here's an example of a list with a title: + +[source] +---- +include::ex-block.adoc[tag=list-title] +---- + +=== Metadata + +In addition to a title, a block can be assigned additional metadata including: + +* Id (i.e., anchor) +* Block name (first positional attribute) +* Block attributes + +Here's an example of a quote block with metadata: + +[source] +---- +include::ex-block.adoc[tag=meta-co] +---- +<1> Title: Gettysburg Address +<2> ID: gettysburg, see <<anchordef>> +<3> Block name: quote +<4> attribution: Abraham Lincoln (Named block attribute) +<5> citetitle: Address delivered at the dedication of the Cemetery at Gettysburg (Named block attribute) + +TIP: A block can have multiple block attribute lines. +The attributes will be aggregated. +If there is a name conflict, the last attribute defined wins. + +Some metadata is used as supplementary content, such as the title, whereas other metadata controls how the block is converted, such as the block name. + +//// +Block id + +NOTE: Pending + +Block Style + +A block style is the first positional attribute in the block attribute list. +//// + +=== Delimited blocks + +The AsciiDoc syntax provides a set of components for including non-paragraph text, such as block quotes, source code listings, sidebars and tables, in your document. +These components are referred to as _delimited blocks_ because they are surrounded by delimiter lines (e.g., `+****+`). + +Here's an example of a sidebar block: + +---- +**** +sidebar block +**** +---- + +Within the boundaries of a delimited block, you can enter any content or blank lines. +The block doesn't end until the ending delimiter is found. +The 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. + +==== Delimiter lines + +The boundaries of a delimited block _must be balanced_. +In other words, the opening delimiter line must be the same length as the closing delimiter line. + +For example, the following delimited block is not balanced and therefore invalid: + +---- +******** +invalid sidebar block +**** +---- + +When the processor encounters the previous example, it will put the remainder of the content in the document inside the delimited block (without warning, currently). +As far as the processor is concerned, the closing delimiter is just a line of content. +If you want the closing delimiter to be matched, it must be the same length as the opening delimiter. + +---- +**** +valid sidebar block +**** +---- + +The AsciiDoc Python processor did not require the delimiters to be balanced, but also never documented that this was permissible. +We view AsciiDoc Python's behavior of matching unbalanced delimited blocks to be a bug and therefore do not allow it in Asciidoctor. + +==== Optional delimiters + +If the content is contiguous (not interrupted by blank lines), you can forgo the use of the block delimiters and instead use the block name above a paragraph to repurpose it as one of the delimited block types. + +This format is often used for single-line listings: + +[source] +.... +include::ex-block.adoc[tag=opt-listing] +.... + +or single-line quotes: + +[source] +---- +include::ex-block.adoc[tag=quote-name] +---- + +==== Masquerading blocks + +Some blocks can masquerade as other blocks, a feature which is controlled by the block name. + +==== Nesting blocks + +You can nest blocks inside each other. +To nest blocks of the same type, add a pair of extra symbols to the delimiter. +For example: + +---- +==== +This is an example +====== +This is an example inside an example +====== +==== +---- + +=== Built-in blocks summary + +The following table identifies the built-in block names and delimited blocks syntax, their purposes, and the substitutions performed on their contents. + +include::block-name-table.adoc[] + +This table shows the substitutions performed by each substitution group referenced in the previous table. + +include::subs-group-table.adoc[] + +TIP: Surround an attribute value with single quotes in order to apply normal substitutions. diff --git a/asciidoc/_includes/book-part.adoc b/asciidoc/_includes/book-part.adoc new file mode 100644 index 0000000..9d39228 --- /dev/null +++ b/asciidoc/_includes/book-part.adoc @@ -0,0 +1,44 @@ +//// +Included in: + +- user-manual +//// + +You may group the sections of your document into parts when you set the `doctype` to `book`. +In fact, parts can only be used when the `doctype` is `book`. + +When a document has its `doctype` set to `book` and contains at least one part, it implicitly becomes a multi-part book. +There is no dedicated doctype value for a multi-part book to distinguish it from a regular book. +That distinction is made by the content. + +Part titles are specified with a single equals sign (`=`), the equivalent to the structure of a document title (i.e., level-0 section). +Each part must contain at least one section (a chapter or special section). +Immediately after the part title, you may insert an optional introduction, which is designated by the `partintro` style. + +[source] +---- +[partintro] +.Optional part introduction title +-- +Optional part introduction goes here. +-- +---- + +A part can also include its own preface, bibliography, glossary and index. + +[source] +---- +include::multi-special-ex.adoc[tag=part] +---- + +When using the PDF converter (i.e., Asciidoctor PDF), the value of the `chapter-label` attribute (followed by a space) is automatically added to the beginning of the chapter title. +A chapter title is a level-1 section title when the doctype is book. + +You can modify this prefix by redefining the `chapter-label` attribute. + +[source] +---- +:chapter-label: Chapter ~ +---- + +To use no prefix, set the value to blank. diff --git a/asciidoc/_includes/callout-copy.adoc b/asciidoc/_includes/callout-copy.adoc new file mode 100644 index 0000000..82cd1a2 --- /dev/null +++ b/asciidoc/_includes/callout-copy.adoc @@ -0,0 +1,27 @@ +//// +Included in: + +- user-manual: callouts: Callouts don't get caught in copy +//// + +In versions prior to Asciidoctor 0.1.4, when a reader visiting an HTML page generated by Asciidoctor selected source code from a listing that contained callouts and copied it, the callout numbers would get caught up in the copied text. +If the reader pasted that code and tried to run it, likely the extra characters from the callouts would cause compile or runtime errors. + +Asciidoctor uses CSS to prevent callouts from being selected. + +On the other side of the coin, you don't want the callout annotations or CSS messing up your raw source code either. +You can tuck your callouts neatly behind line comments. +Asciidoctor will recognize the line comments characters in front of a callout number, optionally offset by a space, and remove them when converting the document. + +Here are the line comments that are supported: + +[source,subs=specialcharacters] +.... +include::ex-callout.adoc[tag=b-nonselect] +.... + +Here's how it looks when rendered: + +==== +include::ex-callout.adoc[tag=b-nonselect] +==== diff --git a/asciidoc/_includes/callout-icon.adoc b/asciidoc/_includes/callout-icon.adoc new file mode 100644 index 0000000..fce9410 --- /dev/null +++ b/asciidoc/_includes/callout-icon.adoc @@ -0,0 +1,14 @@ +//// +Included in: + +- user-manual: callouts: Callout icons +//// + +The font icons setting also enables callout icons drawn using CSS. + +[source] +---- +include::ex-callout.adoc[tag=co-icon] +---- +<1> Activates the font-based icons in the HTML5 backend. +<2> Admonition block that uses a font-based icon. diff --git a/asciidoc/_includes/callout-intro.adoc b/asciidoc/_includes/callout-intro.adoc new file mode 100644 index 0000000..166ba91 --- /dev/null +++ b/asciidoc/_includes/callout-intro.adoc @@ -0,0 +1,24 @@ +Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block. + +Each callout number used in a verbatim block must appear twice. +The first use, which goes within the verbatim block, marks the line being annotated (i.e., the target). +The second use, which goes below the verbatim block, defines the annotation text. +Multiple callout numbers may be used on a single line. + +IMPORTANT: The callout number (at the target) must be placed at the end of the line. + +Here's a basic example of a verbatim block that uses callouts: + +[source,subs=-callouts] +.... +include::ex-callout.adoc[tag=basic] +.... + +Here's how this example gets rendered: + +==== +include::ex-callout.adoc[tag=basic] +==== + +Since callout number can interfere with the syntax of the code they are annotating, Asciidoctor provides several features to hide the callout numbers from both the source and the converted document. +The sections that follow detail these features. diff --git a/asciidoc/_includes/callout-xml.adoc b/asciidoc/_includes/callout-xml.adoc new file mode 100644 index 0000000..95e1bc4 --- /dev/null +++ b/asciidoc/_includes/callout-xml.adoc @@ -0,0 +1,25 @@ +//// +Included in: + +- user-manual: callouts: XML-friendly callouts +//// + +XML doesn't have line comments, so our "`tuck the callout behind a line comment`" trick doesn't work here. +To use callouts in XML, you must place the callout's angled brackets around the the XML comment and callout number. + +Here's how it appears in a listing: + +[source,subs=specialcharacters] +.... +include::ex-callout.adoc[tag=source-xml] +.... + +Here's how it looks when rendered: + +==== +include::ex-callout.adoc[tag=source-xml] +==== + +Notice the comment has been replaced with a circled number that cannot be selected (if not using font icons it will be +rendered differently and selectable). +Now both you and the reader can copy and paste XML source code containing callouts without worrying about errors. diff --git a/asciidoc/_includes/checklist.adoc b/asciidoc/_includes/checklist.adoc new file mode 100644 index 0000000..35c8acc --- /dev/null +++ b/asciidoc/_includes/checklist.adoc @@ -0,0 +1,49 @@ +//// +Included in: + +- user-manual: Unordered lists: Checklists +//// + +List items can be marked complete using checklists. + +Checklists (i.e., task lists) are unordered lists that have items marked as checked (`[*]` or `[x]`) or unchecked (`[ ]`). +Here's an example: + +.Checklist syntax +[source] +---- +include::ex-ulist.adoc[tag=check] +---- + +.Rendered checklist +==== +include::ex-ulist.adoc[tag=check] +==== + +TIP: Not all items in the list have to be checklist items, as the previous example shows. + +When checklists are converted to HTML, the checkbox markup is transformed into an HTML checkbox with the appropriate checked state. +The `data-item-complete` attribute on the checkbox is set to 1 if the item is checked, 0 if not. +The checkbox is used in place of the item's bullet. + +Since HTML generated by Asciidoctor is usually static, the checkbox is set as disabled to make it appear as a simple mark. +If you want to make the checkbox interactive (i.e., clickable), add the `interactive` option to the checklist (shown here using the shorthand syntax for <<Options>>): + +.Checklist with interactive checkboxes +[source] +---- +include::ex-ulist.adoc[tag=check-int] +---- + +.Rendered checklist with interactive checkboxes +==== +include::ex-ulist.adoc[tag=check-int] +==== + +As a bonus, if you enable font-based icons, the checkbox markup (in non-interactive lists) is transformed into a font-based icon! + +.Checklist with font-based checkboxes +[source] +---- +include::ex-ulist.adoc[tag=check-icon] +---- diff --git a/asciidoc/_includes/cli-options.adoc b/asciidoc/_includes/cli-options.adoc new file mode 100644 index 0000000..ef4b16e --- /dev/null +++ b/asciidoc/_includes/cli-options.adoc @@ -0,0 +1,136 @@ +//== Ruby CLI Options + +// DO NOT EDIT THIS FILE +// Copy the content from asciidoctor/man/asciidoctor.adoc + +=== Security Settings + +*-B, --base-dir*=_DIR_:: + Base directory containing the document and resources. + Defaults to the directory containing the source file, or the working directory if the source is read from a stream. + When combined with the safe mode setting, can be used to chroot the execution of the program. + +*-S, --safe-mode*=_SAFE_MODE_:: + Set safe mode level: _unsafe_, _safe_, _server_ or _secure_. + Disables potentially dangerous macros in source files, such as `include::[]`. + If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script. + +*--safe*:: + Set safe mode level to _safe_. + Enables include directives, but prevents access to ancestor paths of source file. + Provided for compatibility with the asciidoc command. + If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script. + +=== Document Settings + +*-a, --attribute*=_ATTRIBUTE_:: + Define, override or delete a document attribute. + Command-line attributes take precedence over attributes defined in the source file unless the value ends with _@_. ++ +_ATTRIBUTE_ is normally formatted as a key-value pair, in the form _NAME=VALUE_. +Alternate acceptable forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unassigns the _NAME_ attribute) and _NAME=VALUE@_ (where _VALUE_ does not override value of _NAME_ attribute if it's already defined in the source document). +Values containing spaces should be enclosed in quotes. ++ +This option may be specified more than once. + +*-b, --backend*=_BACKEND_:: + Backend output file format: _html5_, _docbook5_, _docbook45_ and _manpage_ are supported out of the box. + You can also use the backend alias names _html_ (aliased to _html5_) or _docbook_ (aliased to _docbook5_). + Other values can be passed, but if Asciidoctor cannot resolve the backend to a converter, it will fail. + Defaults to _html5_. + +*-d, --doctype*=_DOCTYPE_:: + Document type: _article_, _book_, _manpage_ or _inline_. + Sets the root element when using the _docbook_ backend and the style class on the HTML body element when using the _html_ backend. + The _book_ document type allows multiple level-0 section titles in a single document. + The _manpage_ document type enables parsing of metadata necessary to produce a man page. + The _inline_ document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element. + Defaults to _article_. + +=== Document Conversion + +*-D, --destination-dir*=_DIR_:: + Destination output directory. + Defaults to the directory containing the source file, or the working directory if the source is read from a stream. + If specified, the directory is resolved relative to the working directory. + +*-E, --template-engine*=_NAME_:: + Template engine to use for the custom converter templates. + The gem with the same name as the engine will be loaded automatically. + This name is also used to build the full path to the custom converter templates. + If a template engine is not specified, it will be auto-detected based on the file extension of the custom converter templates found. + +*-e, --eruby*:: + Specifies the eRuby implementation to use for executing the custom converter templates written in ERB. + Supported values are _erb_ and _erubis_. + Defaults to _erb_. + +*-I, --load-path*=_DIRECTORY_:: + Add the specified directory to the load path, so that _-r_ can load extensions from outside the default Ruby load path. + This option may be specified more than once. + +*-n, --section-numbers*:: + Auto-number section titles. + Synonym for *--attribute sectnums*. + +*-o, --out-file*=_OUT_FILE_:: + Write output to file _OUT_FILE_. + Defaults to the base name of the input file suffixed with _backend_ extension. + The file is resolved relative to the working directory. + If the input is read from standard input or a named pipe (fifo), then the output file defaults to stdout. + If _OUT_FILE_ is _-_, then the output file is written to standard output. + +*-R, --source-dir*=_DIR_:: + Source directory. + Currently only used if the destination directory is also specified. + Used to preserve the directory structure of files converted within this directory in the destination directory. + If specified, the directory is resolved relative to the working directory. + +*-r, --require*=_LIBRARY_:: + Require the specified library before executing the processor, using the standard Ruby require. + This option may be specified more than once. + +*-s, --no-header-footer*:: + Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. + This option is useful for producing documents that can be inserted into an external template. + +*-T, --template-dir*=_DIR_:: + A directory containing custom converter templates that override one or more templates from the built-in set. + (requires _tilt_ gem) ++ +If there is a subfolder that matches the engine name (if specified), that folder is appended to the template directory path. +Similarly, if there is a subfolder in the resulting template directory that matches the name of the backend, that folder is appended to the template directory path. ++ +This option may be specified more than once. +Matching templates found in subsequent directories override ones previously discovered. + +=== Processing Information + +*--failure-level*=_LEVEL_:: + The minimum logging level that triggers a non-zero exit code (failure). + If this option is not set (default: FATAL), the program exits with a status code zero even if warnings or errors have been logged. + +*-q, --quiet*:: + Silence warnings. + +*--trace*:: + Include backtrace information on errors. + Not enabled by default. + +*-v, --verbose*:: + Verbosely print processing information and configuration file checks to stderr. + +*-t, --timings*:: + Display timings information (time to read, parse and convert). + +=== Program Information + +*-h, --help* [_TOPIC_]:: + Print the help message. + Show the command usage if _TOPIC_ is not specified (or not recognized). + Dump the Asciidoctor man page (in troff/groff format) if _TOPIC_ is _manpage_. + +*-V, --version*:: + Print program version number. ++ +`-v` can also be used if no other flags or arguments are present. diff --git a/asciidoc/_includes/colophon.adoc b/asciidoc/_includes/colophon.adoc new file mode 100644 index 0000000..0f75445 --- /dev/null +++ b/asciidoc/_includes/colophon.adoc @@ -0,0 +1,13 @@ +//// +Included in: + +- user-manual +//// + +Book colophons list information such as the ISBN, publishing house, edition and copyright dates, legal notices and disclaimers, cover art, design, and book layout credits, and any significant production notes. +In most mass market books, the colophon is on the verso (back side) of the title page, but it can also be located at the end of the book. + +[source] +---- +include::multi-special-ex.adoc[tag=colophon] +---- diff --git a/asciidoc/_includes/command-line-usage.adoc b/asciidoc/_includes/command-line-usage.adoc new file mode 100644 index 0000000..00273fd --- /dev/null +++ b/asciidoc/_includes/command-line-usage.adoc @@ -0,0 +1,30 @@ +//// +Command line usage quick start for Asciidoctor +This file is included in the install-toolchain and user-manual documents +//// + +Asciidoctor's command line interface (CLI) is a drop-in replacement for the `asciidoc.py` command from the Python implementation. + +If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH. +To confirm that Asciidoctor is available, execute: + + $ asciidoctor --version + +The following information should be output in your terminal: + + Asciidoctor 1.5.6.2 [https://asciidoctor.org] + +To invoke Asciidoctor from the CLI and convert an `.adoc` file, execute: + + $ asciidoctor <asciidoc_file> + +This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the `.html` extension. + +There are many other options available, listed in <<cli-options>>. + +Full help is provided in the {uri-man}[man page] or via: + + $ asciidoctor --help + +There is also an `asciidoctor-safe` command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file. +This mode is very similar to the safe mode of `asciidoc.py`. diff --git a/asciidoc/_includes/comment.adoc b/asciidoc/_includes/comment.adoc new file mode 100644 index 0000000..24dd812 --- /dev/null +++ b/asciidoc/_includes/comment.adoc @@ -0,0 +1,17 @@ +//// +Included in: + +- user-manual: comments +//// + +.Line +---- +include::ex-comment.adoc[tag=line] +---- + +TIP: Single-line comments can be used to divide elements, such as two adjacent lists. + +.Block +---- +include::ex-comment.adoc[tag=bl] +---- diff --git a/asciidoc/_includes/conditional-preprocessor-directives.adoc b/asciidoc/_includes/conditional-preprocessor-directives.adoc new file mode 100644 index 0000000..e455b8d --- /dev/null +++ b/asciidoc/_includes/conditional-preprocessor-directives.adoc @@ -0,0 +1,210 @@ +//// +== Conditional Preprocessor Directives + +Included in: + +- User manual +//// +You can include or exclude lines of text in your document using one of the following conditional preprocessor directives: + +* ifdef +* ifndef +* ifeval + +These directives tell the processor whether to include the enclosed content based on certain conditions. +The conditions are based on the presence or value of document attributes. + +For example, say you want to include a certain section of content only when converting to HTML. +Conditional preprocessor directives make this possible. +You simply check for the presence of the `basebackend-html` attribute using an `ifdef` directive. +Details of this example, as well as others, are described in the following sections. + +=== Processing + +Although a conditional preprocessor directive looks like a block macro, it's not a macro and therefore not processed like one. +Instead, it's a _preprocessor_ directive, just like `include`. +It's important to understand the distinction. + +A preprocessor directive is processed when the lines are read, but before the document structure is parsed. +Therefore, it's _not_ aware of the surrounding document structure. +A preprocessor directive merely adds lines to the reader or takes lines away. +The conditional preprocessor directives determine which lines to add and which ones to take away based on the condition. + +If you don't want a conditional preprocessor directive to be processed, you must escape it using a backslash. + + \ifdef::just-an-example[] + +Escaping the directive is necessary _even if it appears in a verbatim block_ since it's not aware of the surrounding document structure. + +=== ifdef Directive + +Content between the `ifdef` and `endif` directives gets included if the specified attribute is set: + +.ifdef example +---- +\ifdef::env-github[] +This content is for GitHub only. +\endif::[] +---- + +The syntax of the start directive is `ifdef::<attribute>[]`, where `<attribute>` is the name of an attribute. + +Keep in mind that the content is not limited to a single line. +You can have any amount of content between the `ifdef` and `endif` directives. + +If you have a large amount of content inside the `ifdef` directive, you may find it more readable to use the long-form version of the directive, in which the attribute (aka condition) is referenced again in the `endif` directive. + +.ifdef long-form example +---- +\ifdef::env-github[] +This content is for GitHub only. + +So much content in this section, I'd get confused reading the source without the closing `ifdef` directive. + +It isn't necessary for short blocks, but if you are conditionally including a section it may be something worth considering. + +Other readers reviewing your docs source code may go cross-eyed when reading your source docs if you don't. +\endif::env-github[] +---- + +TIP: A great example of long-form conditional formatting is the source of this user manual! +We use it to show and hide entire sections when building individual content for separate guides. + +If you're only dealing with a single line of text, you can put the content directly inside the square brackets and drop the `endif` directive. + +.ifdef single line example +---- +\ifdef::revnumber[This document has a version number of {revnumber}.] +---- + +The single-line block above is equivalent to this formal `ifdef` directive: + +[source] +---- +\ifdef::revnumber[] +This document has a version number of {revnumber}. +\endif::[] +---- + +=== ifndef Directive + +`ifndef` is the logical opposite of `ifdef`. +Content between `ifndef` and `endif` gets included only if the specified attribute is _not_ set: + +.ifndef Example +---- +\ifndef::env-github[] +This content is not shown on GitHub. +\endif::[] +---- + +The syntax of the start directive is `ifndef::<attribute>[]`, where `<attribute>` is the name of an attribute. + +The `ifndef` directive supports the same single-line and long-form variants as `ifdef`. + +=== Checking multiple attributes (ifdef and ifndef only) + +Both the `ifdef` and `ifndef` directives accept multiple attribute names. +The combinator can be "`and`" or "`or`". + +Any attribute (or):: +Multiple comma-separated (,) directive names evaluate to true, allowing the content to be included, if one or more of the directives is defined. +Otherwise the content is not included. ++ +.Any attribute example +---- +\ifdef::backend-html5,backend-docbook5[Only shown when converting to HTML5 or DocBook 5.] +---- + +All attributes (and):: +Multiple plus-separated (+) directive names evaluate to true, allowing the content to be included, if all of the directives are defined. +Otherwise the content is not included. ++ +.All attributes example +---- +\ifdef::env-github+backend-html5[Only shown when converting to HTML5 on GitHub.] +---- + +The `ifndef` directive negates the results of the expression. + +WARNING: Starting in Asciidoctor 1.5.6, the operator logic in the `ifndef` directive changed to align with the behavior of AsciiDoc Python. +Specifically, when attributes are separated by commas, content is only included if none of the attributes are defined. +When attributes are separated by pluses, content is included if at least one of the attributes is undefined. +See https://github.com/asciidoctor/asciidoctor/issues/1983[issue #1983] to find the discussion about this behavior and the rationale for the change. + +=== ifeval directive + +Content between `ifeval` and `endif` gets included if the expression inside the square brackets evaluates to true. + +.ifeval example +---- +\ifeval::[{sectnumlevels} == 3] +If the `sectnumlevels` attribute has the value 3, this sentence is included. +\endif::[] +---- + +The `ifeval` directive does not have a single-line or long-form variant like `ifdef` and `ifndef`. + +==== Anatomy + +The expression consists of a left-hand value and a right-hand value with an operator in between. + +.ifeval expression examples +---- +\ifeval::[2 > 1] +... +\endif::[] + +\ifeval::["{backend}" == "html5"] +... +\endif::[] + +\ifeval::[{sectnumlevels} == 3] +... +\endif::[] + +// the value of outfilesuffix includes a leading period (e.g., .html) +\ifeval::["{docname}{outfilesuffix}" == "master.html"] +... +\endif::[] +---- + +==== Values + +Each expression value can reference the name of zero or more AsciiDoc attribute using the attribute reference syntax (for example, `+{backend}+`). + +Attribute references are resolved (substituted) first. +Once attributes references have been resolved, each value is coerced to a recognized type. + +When the expected value is a string (i.e., a string of characters), we recommend that you enclose the expression in quotes. + +The following values types are recognized: + +number:: Either an integer or floating-point value. +quoted string:: Enclosed in either single (') or double (") quotes. +boolean:: Literal value of `true` or `false`. + +===== How value type coercion works + +If a value is enclosed in quotes, the characters between the quotes are preserved and coerced to a string. + +If a value is not enclosed in quotes, it is subject to the following type coercion rules: + +* an empty value becomes nil (aka null). +* a value of `true` or `false` becomes a boolean value. +* a value of only repeating whitespace becomes a single whitespace string. +* a value containing a period becomes a floating-point number. +* any other value is coerced to an integer value. + +==== Operators + +The value on each side is compared using the operator to derive an outcome. + +`==`:: Checks if the two values are equal. +`!=`:: Checks if the two values are not equal. +`<`:: Checks whether the left-hand side is less than the right-hand side. +`+<=+`:: Checks whether the left-hand side is less than or equal to the right-hand side. +`>`:: Checks whether the left-hand side is greater than the right-hand side. +`+>=+`:: Checks whether the left-hand side is greater than or equal to the right-hand side. + +NOTE: The operators follow the same rules as operators in Ruby. diff --git a/asciidoc/_includes/convert-from-confluence-xhtml.adoc b/asciidoc/_includes/convert-from-confluence-xhtml.adoc new file mode 100644 index 0000000..7edf87d --- /dev/null +++ b/asciidoc/_includes/convert-from-confluence-xhtml.adoc @@ -0,0 +1,32 @@ +//// +Header: Convert Confluence XHTML to AsciiDoc + +Included in: + +- user-manual +//// +You can convert Atlassian Confluence XHTML pages to Asciidoctor using this http://www.groovy-lang.org/download.html[Groovy] script. + +The script calls https://pandoc.org/[Pandoc] to convert single or multiple HTML files exported from Confluence to AsciiDoc files. +You'll need Pandoc installed before running this script. + +NOTE: If you have trouble running this script, you can use the Pandoc command referenced inside the script to convert XHTML files to AsciiDoc manually. + +.convert.groovy +[source,groovy] +---- +include::https://gist.githubusercontent.com/melix/6020336/raw/059d83a3dae933de71d585c3f6b229a3c62fa857/convert.groovy[] +---- + +The script is designed to be run locally on HTML files or directories containing HTML files exported from Confluence. + +.Usage +. Save the script contents to a `convert.groovy` file in a working directory. +. Make the file executable according to your specific OS requirements. +. Place individual files, or a directory containing files into the working directory. +. Run `groovy convert filename.html` to convert a single file. +. Confirm the output file meets requirements +. Recurse through a directory by using this command pattern: `groovy convert directory/*.html` + +This script was created by Cédric Champeau (https://gist.github.com/melix[melix]). +You can find the source of this script hosted at this https://gist.github.com/melix/6020336[GitHub Gist]. diff --git a/asciidoc/_includes/counter.adoc b/asciidoc/_includes/counter.adoc new file mode 100644 index 0000000..8e4a6ad --- /dev/null +++ b/asciidoc/_includes/counter.adoc @@ -0,0 +1,92 @@ +//// +Included in: + +- user-manual: Counters +//// + +// document attributes and counters are NOT the same thing, but modifying a document attribute with the same name as the counter modifies the counter at the same time. + +Counters are used to store and display ad-hoc sequences of numbers or latin characters. +They are designed for simple use cases. +Possible uses include inline itemized lists, paragraph numbers and serial item numbers. + +A counter is implemented as a specialized document attribute. +You declare and display a counter using an augmented attribute reference, in which the attribute name is prefixed with `counter:` (e.g., `+{counter:name}+`). +Since counters are attributes, counter names follow the same rules as <<attribute-restrictions,attribute names>>. +The most important rule to note is that letters in counter names _must be lowercase_. + +The counter value is incremented and displayed every time the `counter:` attribute reference is used. +The term [.term]_increment_ means advance to the next value in the sequence. +If the counter value is an integer, add 1. +If the counter value is a character, move to the next letter in the Latin alphabet. +The default start value of a counter is 1. + +To create a sequence starting at 1, use the simple form `+{counter:name}+` as shown here: + +[source] +The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. + +Here's the resulting output: + +==== +:!seq1: +The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. +==== + +To increment the counter without displaying it (i.e., to skip an item in the sequence), use the `counter2` prefix instead: + +[source] +{counter2:seq1} + +WARNING: A `counter2` attribute reference on a line by itself will produce an empty paragraph. +You'll need to adjoin it to the nearest content to avoid this side effect. + +To display the current value of the counter without incrementing it, reference the counter name as you would any other attribute: + +[source] +{counter2:pnum}This is paragraph {pnum}. + +To create a character sequence, or start a number sequence with a value other than 1, specify a start value by appending it to the first use of the counter: + +[source] +Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries. + +CAUTION: Character sequences either run from a,b,c,...x,y,z,{,|... or A,B,C,...,X,Y,Z,[,... depending on the start value. +Therefore, they aren't really useful for more than 26 items. + +The start value of a counter is only recognized if the counter is _unset_ at that point in the document. +Otherwise, the start value is ignored. + +To reset a counter attribute, unset the corresponding attribute using an attribute entry. +The attribute entry must be adjacent to a block or else it is ignored. + +[source] +---- +The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. + +:!seq1: +Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries. +---- + +This gives: + +==== +:!seq1: +The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. + +:!seq1: +Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries. +==== + +Here's a full example that shows how to use a counter for part numbers in a table. + +[source] +---- +include::ex-counter.adoc[tag=base] +---- + +Here's the output of that table: + +==== +include::ex-counter.adoc[tag=base] +==== diff --git a/asciidoc/_includes/create-theme.adoc b/asciidoc/_includes/create-theme.adoc new file mode 100644 index 0000000..45210b5 --- /dev/null +++ b/asciidoc/_includes/create-theme.adoc @@ -0,0 +1,40 @@ +//// +Custom Themes +Creating a theme + +This document is included in: + +- user-manual +//// + +You can create your own themes to apply to your documents. + +Themes go in the [.path]_sass/_ folder. +To create a new theme, let's call it `hipster`, start by creating two new files: + +[.path]_sass/hipster.scss_:: + * Imports the theme settings, which includes default variables and resets + * Imports the AsciiDoc components + * Defines any explicit customization + +[.path]_sass/settings/_hipster.scss_:: + * Sets variables that customize Foundation 4 and the AsciiDoc CSS components + +Here's a minimal version of [.path]_sass/hipster.scss_: + +[source,scss] +---- +@import "settings/hipster"; +@import "components/asciidoc"; +@import "components/awesome-icons"; +---- + +NOTE: You don't have to include the underscore prefix when importing files. + +NOTE: The `awesome-icons` component is only applicable to HTML generated by Asciidoctor > 0.1.2 with the `icons` attribute set to `font`. + +You can add any explicit customization below the import lines. + +The variables you can set in [.path]_sass/settings/_hipster.scss_ are a combination of the {factory-ref}/blob/master/sass/settings/_settings.scss.dist[Foundation 4 built-in global settings] and {factory-ref}/blob/master/sass/settings/_defaults.scss[global settings and imports for the AsciiDoc components]. + +Once you've created your custom theme, it's time to apply it to your document. diff --git a/asciidoc/_includes/dedication.adoc b/asciidoc/_includes/dedication.adoc new file mode 100644 index 0000000..f8d6599 --- /dev/null +++ b/asciidoc/_includes/dedication.adoc @@ -0,0 +1,12 @@ +//// +Included in: + +- user-manual +//// + +The dedication page is where the author expresses gratitude toward a person. + +[source] +---- +include::multi-special-ex.adoc[tag=dedicate] +---- diff --git a/asciidoc/_includes/discrete-heading.adoc b/asciidoc/_includes/discrete-heading.adoc new file mode 100644 index 0000000..a2521ba --- /dev/null +++ b/asciidoc/_includes/discrete-heading.adoc @@ -0,0 +1,33 @@ +//// +Sections + +Included in: + +- user-manual +//// + +To make a discrete heading, you add the `discrete` attribute to any <<Sections,section title>>. +//This demotes the section title to a normal heading. +A discrete heading is styled in a manner similar to a section title, but is not part of the section hierarchy (i.e., and thus excluded from section nesting requirements), it does not enclose subsequent blocks, and it is not included in the table of contents. +The `discrete` style effectively demotes the section title to a normal heading. + +NOTE: Alternately, you may use the `float` attribute to identify a discrete heading. +In this context, the term "`float`" does not imply layout, meaning it does not float to the left or right of other content blocks. +It just means it's not anchored to the section hierarchy. + +Here's an example of a discrete heading in use. + +[source] +---- +**** // <1> +Discrete headings are useful for making headings inside of other blocks, like this sidebar. + +[discrete] // <2> +== Discrete Heading // <3> + +Discrete headings can be used where sections are not permitted. +**** +---- +<1> A delimiter line that indicates the start of a sidebar block. +<2> Set the `discrete` attribute above the section title to demote it to a discrete heading. +<3> The discrete heading title is designated by one to six equal signs, just like a section title. diff --git a/asciidoc/_includes/dlist-qa.adoc b/asciidoc/_includes/dlist-qa.adoc new file mode 100644 index 0000000..ad1acf8 --- /dev/null +++ b/asciidoc/_includes/dlist-qa.adoc @@ -0,0 +1,15 @@ +//// +Included in: + +- user-manual: Question and answer style list +//// + +.Q&A +[source] +---- +include::ex-dlist.adoc[tag=qa] +---- + +==== +include::ex-dlist.adoc[tag=qa] +==== diff --git a/asciidoc/_includes/dlist.adoc b/asciidoc/_includes/dlist.adoc new file mode 100644 index 0000000..9c5320e --- /dev/null +++ b/asciidoc/_includes/dlist.adoc @@ -0,0 +1,84 @@ +//// +Included in: + +- user-manual: Description lists +- writers-guide: description lists +- writers-guide: hybrid lists +//// + +// tag::description[] +A description list (often abbreviate as dlist) is useful when you need to include a description or supporting text for one or more terms. +Each item in a description list consists of: + +* one or more terms +* a separator following each term (typically a double colon, `::`) +* at least one space or endline +* the supporting content (either text, attached blocks, or both) + +Here's an example of a description list that identifies parts of a computer: + +[source] +---- +include::ex-dlist.adoc[tag=base] +---- + +By default, the content of each item is displayed below the description when rendered. +Here's a preview of how this list is rendered: + +.A basic description list +==== +include::ex-dlist.adoc[tag=base] +==== + +If you want the description and content to appear on the same line, add the horizontal style to the list. + +[source] +---- +include::ex-dlist.adoc[tag=base-horz] +---- + +==== +include::ex-dlist.adoc[tag=base-horz] +==== + +The content of a description list can be any AsciiDoc element. +For instance, we could rewrite the grocery list from above so that each aisle is a description rather than a parent outline list item. + +[source] +---- +include::ex-dlist.adoc[tag=base-mix] +---- + +==== +include::ex-dlist.adoc[tag=base-mix] +==== + +Description 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: + +[source] +---- +include::ex-dlist.adoc[tag=base-mix-alt] +---- +// end::description[] + +// tag::hybrid[] +[#three-hybrid] +Finally, you can mix and match the three list types within a single hybrid list. +Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans. + +Here's a list that mixes description, ordered, and unordered list items: + +[source] +---- +include::ex-dlist.adoc[tag=3-mix] +---- + +Here's how the list is rendered: + +.A hybrid list +==== +include::ex-dlist.adoc[tag=3-mix] +==== + +You can include more complex content in a list item as well. +// end::hybrid[] diff --git a/asciidoc/_includes/docbook.adoc b/asciidoc/_includes/docbook.adoc new file mode 100644 index 0000000..648c3c7 --- /dev/null +++ b/asciidoc/_includes/docbook.adoc @@ -0,0 +1,84 @@ +//// +Included in: + +- user-manual: DocBook +//// + +Asciidoctor can produce DocBook 5.0 output. +Since the AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good. +There's a corresponding DocBook element for each markup in the AsciiDoc syntax. + +To convert the `mysample.adoc` document to DocBook 5.0 format, call the processor with the backend flag set to `docbook`. + + $ asciidoctor -b docbook mysample.adoc + +A new XML document, named `mysample.xml`, will now be present in the current directory. + + $ ls + mysample.adoc mysample.html mysample.xml + +Here's a snippet of the XML generated by the DocBook converter. + +.XML generated from AsciiDoc +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<article xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info> + <title>Hello, AsciiDoc! + 2013-09-03 + + + Doc + Writer + + doc@example.com + + DW + + + An introduction to AsciiDoc. + +
+ First Section + + + item 1 + + + item 2 + + +
+ +---- + +If you're on Linux, you can view the DocBook file with {uri-yelp}[Yelp]. + + $ yelp mysample.xml + +And of course, if you're using the Asciidoctor Ruby API, you can generate a DocBook document directly from your application. + +.Generate DocBook output from the API +[source,ruby] +---- +Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook' +---- + +By default, the docbook converter produces DocBook 5.0 output that is compliant to the DocBook 5.0 specification. + +A summary of the differences are as follows: + +* XSD declarations are used on the document root instead of a DTD +* `` elements for document info instead of `` and `` +* elements that hold the author's name are wrapped in a `` element +* the id for an element is defined using an `xml:id` attribute +* `` is used for links instead of `` +* the URL for a link is defined using the `xl:href` attribute + +Refer to {uri-docbook5}[What's new in DocBook v5.0?] for more details about how DocBook 5.0 differs from DocBook 4.5. + +If you need to output DocBook 4.5, you may find the community-supported {uri-docbook45}[DocBook 4.5 Converter] useful. + + $ asciidoctor -b docbook45 mysample.adoc diff --git a/asciidoc/_includes/docbookrx.adoc b/asciidoc/_includes/docbookrx.adoc new file mode 100644 index 0000000..d2019fa --- /dev/null +++ b/asciidoc/_includes/docbookrx.adoc @@ -0,0 +1,20 @@ +//// +Included in: + +- user-manual: Convert DocBook XML to AsciiDoc +//// + +One of the things Asciidoctor excels at is converting AsciiDoc source into valid and well-formed DocBook XML content. + +What if you're in the position where you need to go the other way: migrate all your legacy DocBook XML content to AsciiDoc? +The prescription (℞) you need to get rid of your DocBook pains could be https://github.com/opendevise/docbookrx[DocBookRx]. + +DocBookRx is an early version of a DocBook to AsciiDoc converter written in Ruby. +This converter is far from perfect at the moment, but it improves with each document it converts. + +The plan is to evolve it into a robust library for performing this conversion in a reliable way. +You can read more about this initiative in the https://github.com/opendevise/docbookrx/blob/master/README.adoc[README]. + +The best thing about this tool is all the active users who are putting it through its paces. +The more advanced the DocBook XML this tool tackles, and the more feedback we receive, the better the tool will become. +Use it today to escape from XML hell! diff --git a/asciidoc/_includes/docinfo.adoc b/asciidoc/_includes/docinfo.adoc new file mode 100644 index 0000000..84bb854 --- /dev/null +++ b/asciidoc/_includes/docinfo.adoc @@ -0,0 +1,246 @@ +//// +Included in: + +- user-manual: docinfo +//// + +You can add custom content to the head or footer of an output document using docinfo files. +Docinfo files are useful for injecting auxiliary metadata, stylesheet, and script information into the output not added by the converter. + +Different docinfo files get used depending on whether you are converting to HTML or DocBook (but don't yet apply when converting to PDF). + +=== Head docinfo files + +The content of head docinfo files gets injected into the top of the document. +For HTML, the content is append to the `` element. +For DocBook, the content is appended to the root `` element. + +The docinfo file for HTML output may contain valid elements to populate the HTML `` element, including: + +* `` +* `` +* `` +* `