From 64ec52d2dacb0ff9c5e54ff47bc35f56a67b18ea Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 19 Nov 2020 15:45:59 -0700 Subject: create integration modules; update stylesheet pages --- docs/modules/ROOT/nav-safe-modes.adoc | 2 +- .../ROOT/pages/attributes-and-safe-modes.adoc | 46 ------ docs/modules/ROOT/pages/language-support.adoc | 46 +++--- docs/modules/ROOT/pages/reference-safe-mode.adoc | 45 ++++++ docs/modules/ROOT/pages/safe-modes.adoc | 6 +- docs/modules/api/pages/set-safe-mode.adoc | 5 +- docs/modules/cli/pages/process-multiple-files.adoc | 2 +- docs/modules/cli/pages/set-safe-mode.adoc | 7 +- docs/modules/html-backend/nav.adoc | 4 +- .../html-backend/pages/apply-code-stylesheets.adoc | 27 ---- .../html-backend/pages/apply-stylesheet.adoc | 97 ------------- .../html-backend/pages/custom-stylesheets.adoc | 97 +++++++++++++ docs/modules/html-backend/pages/index.adoc | 2 +- .../html-backend/pages/manage-stylesheets.adoc | 11 +- .../pages/source-highlighting-stylesheets.adoc | 27 ++++ docs/modules/integrations/nav.adoc | 9 -- docs/modules/integrations/pages/asciimath-gem.adoc | 39 ------ docs/modules/integrations/pages/coderay.adoc | 107 -------------- docs/modules/integrations/pages/highlightjs.adoc | 42 ------ docs/modules/integrations/pages/mathjax.adoc | 7 - docs/modules/integrations/pages/pygments.adoc | 156 --------------------- docs/modules/integrations/pages/rouge.adoc | 70 --------- docs/modules/integrations/pages/stem.adoc | 15 -- .../integrations/pages/syntax-highlighters.adoc | 26 ---- docs/modules/manpage-backend/pages/index.adoc | 35 ++--- docs/modules/migrate/pages/asciidoc-python.adoc | 2 +- docs/modules/source-highlighters/nav.adoc | 5 + .../modules/source-highlighters/pages/coderay.adoc | 107 ++++++++++++++ .../source-highlighters/pages/highlightjs.adoc | 42 ++++++ docs/modules/source-highlighters/pages/index.adoc | 32 +++++ .../source-highlighters/pages/pygments.adoc | 156 +++++++++++++++++++++ docs/modules/source-highlighters/pages/rouge.adoc | 70 +++++++++ docs/modules/stem/nav.adoc | 3 + docs/modules/stem/pages/asciimath-gem.adoc | 39 ++++++ docs/modules/stem/pages/index.adoc | 14 ++ docs/modules/stem/pages/mathjax.adoc | 7 + 36 files changed, 708 insertions(+), 699 deletions(-) delete mode 100644 docs/modules/ROOT/pages/attributes-and-safe-modes.adoc create mode 100644 docs/modules/ROOT/pages/reference-safe-mode.adoc delete mode 100644 docs/modules/html-backend/pages/apply-code-stylesheets.adoc delete mode 100644 docs/modules/html-backend/pages/apply-stylesheet.adoc create mode 100644 docs/modules/html-backend/pages/custom-stylesheets.adoc create mode 100644 docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc delete mode 100644 docs/modules/integrations/nav.adoc delete mode 100644 docs/modules/integrations/pages/asciimath-gem.adoc delete mode 100644 docs/modules/integrations/pages/coderay.adoc delete mode 100644 docs/modules/integrations/pages/highlightjs.adoc delete mode 100644 docs/modules/integrations/pages/mathjax.adoc delete mode 100644 docs/modules/integrations/pages/pygments.adoc delete mode 100644 docs/modules/integrations/pages/rouge.adoc delete mode 100644 docs/modules/integrations/pages/stem.adoc delete mode 100644 docs/modules/integrations/pages/syntax-highlighters.adoc create mode 100644 docs/modules/source-highlighters/nav.adoc create mode 100644 docs/modules/source-highlighters/pages/coderay.adoc create mode 100644 docs/modules/source-highlighters/pages/highlightjs.adoc create mode 100644 docs/modules/source-highlighters/pages/index.adoc create mode 100644 docs/modules/source-highlighters/pages/pygments.adoc create mode 100644 docs/modules/source-highlighters/pages/rouge.adoc create mode 100644 docs/modules/stem/nav.adoc create mode 100644 docs/modules/stem/pages/asciimath-gem.adoc create mode 100644 docs/modules/stem/pages/index.adoc create mode 100644 docs/modules/stem/pages/mathjax.adoc (limited to 'docs/modules') diff --git a/docs/modules/ROOT/nav-safe-modes.adoc b/docs/modules/ROOT/nav-safe-modes.adoc index be07ed4d..2d362d52 100644 --- a/docs/modules/ROOT/nav-safe-modes.adoc +++ b/docs/modules/ROOT/nav-safe-modes.adoc @@ -1,2 +1,2 @@ * xref:safe-modes.adoc[] -** xref:attributes-and-safe-modes.adoc[] +** xref:reference-safe-mode.adoc[] diff --git a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc deleted file mode 100644 index 1d18c502..00000000 --- a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= Manage Attributes By Safe Mode -// anchor: set-safe-attrs - -Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. -Each level includes the restrictions enabled in the prior security level. - -Asciidoctor provides access to the xref:safe-modes.adoc[current safe mode] through built-in attributes. -You can use these attributes to enable or disable content based on the current safe mode of the processor. - -The safe mode can be referenced by one of the following attributes: - -* The value of the `safe-mode-name` attribute (e.g., unsafe, safe, etc.) -* The value of the `safe-mode-level` attribute (e.g., 0, 10, etc.) -* The presence of the `safe-mode-` attribute, where `` is the safe mode name. - -The attributes in the next example define replacement text for features that are disabled in high security environments: - -[source,asciidoc] ----- -\ifdef::safe-mode-secure[] -Link to chapters instead of including them. -\endif::safe-mode-secure[] ----- - -This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure. - -You can set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and the xref:api:set-safe-mode.adoc[API]. - -//// -Allow the include directive to import a file from a URI. - -Example: - - include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[] - -To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater. -Since this is a potentially dangerous feature, 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. - -I decided the following defaults for the standalone option make the most sense: - -true if using the cli (use -s to disable, consistent with asciidoc) -false if using the API, unless converting directly to a file, in which case true is the default -The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting. - -The reason I think the standalone default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now. -//// diff --git a/docs/modules/ROOT/pages/language-support.adoc b/docs/modules/ROOT/pages/language-support.adoc index 4af521ff..362411d0 100644 --- a/docs/modules/ROOT/pages/language-support.adoc +++ b/docs/modules/ROOT/pages/language-support.adoc @@ -39,85 +39,85 @@ If you're not using the DocBook toolchain for publishing, you must translate eac One way is to set the following attributes in the document header or by passing the attributes via the API or CLI: .Attributes that control built-in labels -[%autowidth] +[%autowidth,cols="m,,"] |=== -|Attribute name |Used for |Default +|Attribute |Default English Value |Notes |appendix-caption -|Appendix titles. |Appendix +| |caution-caption -|CAUTION admonitions (when icons are not in use). |Caution +| |chapter-label -|Prefix added to chapter titles (i.e., level-1 section titles when doctype is book). _(pdf converter only)_ |Chapter +|Applies only when `doctype` is `book`. +PDF converter only. |example-caption -|Example titles. |Example +| |figure-caption -|Automatically prefixed to figure titles. |Figure +| |important-caption -|IMPORTANT admonitions (when icons are not in use). |Important +| |last-update-label -|Label for when the document was last updated. |Last updated +| |listing-caption -|The label for listing blocks. -By default, listing blocks do not have captions. -If you specify `listing-caption`, then you also turn on captions for listing blocks. |_not set_ +|By default, listing blocks do not have captions. +Specify `listing-caption` to turn on listing block captions. |manname-title -|Label for the program name section in the man page. |NAME +|Applies only when `doctype` is `manpage`. |note-caption -|NOTE admonitions (when icons are not in use). |Note +| |preface-title -|Title text used for the anonymous preface (when the `doctype` is book). |_not set_ +|Applies only when `doctype` is `book`. |table-caption -|Automatically prefixed to table titles. |Table +| |tip-caption -|TIP admonitions (when icons are not in use). |Tip +| |toc-title -|Title of the table of contents. |Table of Contents +| |untitled-label -|The document title, for documents that have only body content. |Untitled +| |version-label -|The label preceding the revnumber in the document's byline. |Version +| |warning-caption -|WARNING admonitions (when icons are not in use). |Warning +| |=== -If you plan to support multiple languages, you'll want to define the attributes for each language inside a conditional preprocessor directive. +If you plan to support multiple languages, you'll want to define the attributes for each language inside a xref:asciidoc:directives:conditionals.adoc[conditional preprocessor directive]. For example: -[source] +[source,asciidoc] ---- \ifeval::["{lang}" == "de"] :caution-caption: Achtung diff --git a/docs/modules/ROOT/pages/reference-safe-mode.adoc b/docs/modules/ROOT/pages/reference-safe-mode.adoc new file mode 100644 index 00000000..8c5b47b2 --- /dev/null +++ b/docs/modules/ROOT/pages/reference-safe-mode.adoc @@ -0,0 +1,45 @@ += Safe Mode Specific Content +// anchor: set-safe-attrs + +Asciidoctor provides access to the xref:safe-modes.adoc[current safe mode] through built-in attributes. +You can use these attributes to enable or disable content based on the current safe mode of the processor. + +== Referencing safe modes + +The safe mode can be referenced by one of the following attributes: + +* The value of the `safe-mode-name` attribute (e.g., unsafe, safe, etc.) +* The value of the `safe-mode-level` attribute (e.g., 0, 10, etc.) +* The presence of the `safe-mode-` attribute, where `` is the safe mode name. + +The attributes in the next example define replacement text for features that are disabled in high security environments: + +[source,asciidoc] +---- +\ifdef::safe-mode-secure[] +Link to chapters instead of including them. +\endif::safe-mode-secure[] +---- + +This feature is particularly handy for displaying content on GitHub, where the safe mode is set to its most restrictive setting, secure. + +You can set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and the xref:api:set-safe-mode.adoc[API]. + +//// +Allow the include directive to import a file from a URI. + +Example: + + include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[] + +To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater. +Since this is a potentially dangerous feature, 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. + +I decided the following defaults for the standalone option make the most sense: + +true if using the cli (use -s to disable, consistent with asciidoc) +false if using the API, unless converting directly to a file, in which case true is the default +The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting. + +The reason I think the standalone default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now. +//// diff --git a/docs/modules/ROOT/pages/safe-modes.adoc b/docs/modules/ROOT/pages/safe-modes.adoc index 3e06f836..c8ac7d8f 100644 --- a/docs/modules/ROOT/pages/safe-modes.adoc +++ b/docs/modules/ROOT/pages/safe-modes.adoc @@ -1,6 +1,6 @@ = Safe Modes -Asciidoctor provides security levels that control the read and write access of attributes, the include directive, macros, and scripts while a document is processing. +Asciidoctor provides security levels that control the read and write access of attributes, include directives, macros, and scripts while a document is processing. Each level includes the restrictions enabled in the prior security level. == Safe mode levels @@ -48,7 +48,7 @@ Additionally, it: * disables `docdir` and `docfile` (as these can reveal information about the host filesystem) * disables source highlighting -xref:extensions:register.adoc[Asciidoctor extensions] may still embed content into the document depending whether they honor the safe mode setting. +xref:extensions:index.adoc[Asciidoctor extensions] may still embed content into the document depending whether they honor the safe mode setting. *This is the default safe mode for the API.* Its integer value is `20`. @@ -80,4 +80,4 @@ TIP: GitHub processes AsciiDoc files using the `SECURE` level. //// The safe mode can be set from the xref:cli:set-safe-mode.adoc[CLI] and the xref:api:set-safe-mode.adoc[API]. -You can also xref:attributes-and-safe-modes.adoc[manage attributes by safe mode]. +You can also xref:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc index dcf13af6..8ff65b5d 100644 --- a/docs/modules/api/pages/set-safe-mode.adoc +++ b/docs/modules/api/pages/set-safe-mode.adoc @@ -3,6 +3,9 @@ The default xref:ROOT:safe-modes.adoc[safe mode] in the API is `SECURE`. You can change the safe mode using a string, symbol or integer value. + +== Set :safe option + The value must be set in the document constructor using the `:safe` option. result = Asciidoctor.convert_file('master.adoc', :safe => 'server') @@ -15,4 +18,4 @@ or result = Asciidoctor.convert_file('master.adoc', :safe => 10) -You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode]. +You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. diff --git a/docs/modules/cli/pages/process-multiple-files.adoc b/docs/modules/cli/pages/process-multiple-files.adoc index 0d565b77..db6368e5 100644 --- a/docs/modules/cli/pages/process-multiple-files.adoc +++ b/docs/modules/cli/pages/process-multiple-files.adoc @@ -45,4 +45,4 @@ Most shells do not honor this double glob pattern. In conclusion, when specifying a glob pattern, we always recommend enclosing the argument in quotes. -CAUTION: To process multiple nested AsciiDoc files at once and apply a custom stylesheet, you'll need to xref:html-backend:apply-stylesheet.adoc#style-nested[manage the stylesheet's location]. +CAUTION: To process multiple nested AsciiDoc files at once and apply a custom stylesheet, you'll need to xref:html-backend:custom-stylesheets.adoc#style-nested[manage the stylesheet's location]. diff --git a/docs/modules/cli/pages/set-safe-mode.adoc b/docs/modules/cli/pages/set-safe-mode.adoc index 31110060..66db3565 100644 --- a/docs/modules/cli/pages/set-safe-mode.adoc +++ b/docs/modules/cli/pages/set-safe-mode.adoc @@ -1,7 +1,10 @@ = Set the Safe Mode Using the CLI -:navtitle: Set the Safe Mode +:navtitle: Set Safe Mode When Asciidoctor is invoked via the CLI, the xref:ROOT:safe-modes.adoc[safe mode] is set to `UNSAFE` by default. + +== Assign safe mode level + You can change the security level by executing one of the following commands: `-S`, `--safe-mode=SAFE_MODE`:: @@ -16,4 +19,4 @@ Provided for compatibility with the python AsciiDoc `safe` command. 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. Can be used as a way to chroot the execution of the program. //// -You can also set the xref:api:set-safe-mode.adoc[safe mode from the API] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode]. +You can also set the xref:api:set-safe-mode.adoc[safe mode from the API] and xref:ROOT:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. diff --git a/docs/modules/html-backend/nav.adoc b/docs/modules/html-backend/nav.adoc index aa1054cb..396b226a 100644 --- a/docs/modules/html-backend/nav.adoc +++ b/docs/modules/html-backend/nav.adoc @@ -1,7 +1,7 @@ * xref:index.adoc[] ** xref:manage-stylesheets.adoc[] -** xref:apply-code-stylesheets.adoc[] -** xref:apply-stylesheet.adoc[] +** xref:source-highlighting-stylesheets.adoc[] +** xref:custom-stylesheets.adoc[] ** xref:favicon.adoc[] ** xref:manage-images.adoc[] ** xref:favicon.adoc[] diff --git a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc b/docs/modules/html-backend/pages/apply-code-stylesheets.adoc deleted file mode 100644 index 42be39cb..00000000 --- a/docs/modules/html-backend/pages/apply-code-stylesheets.adoc +++ /dev/null @@ -1,27 +0,0 @@ -= Apply CodeRay or Pygments Stylesheets -// um anchor: hl-css -// html-code-styles.adoc, included in convert-documents and the user-manual. - -Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters. - -== Requirements - -First, make sure the appropriate library is installed on your system. -See xref:integrations:rouge.adoc[], xref:integrations:coderay.adoc[], or xref:integrations:pygments.adoc[] for installation instructions. -Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed. - -[#coderay] -== CodeRay - -If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is: - -* _embedded_ by default -* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set - -[#pygments] -== Pygments - -If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is: - -* _embedded_ by default -* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set diff --git a/docs/modules/html-backend/pages/apply-stylesheet.adoc b/docs/modules/html-backend/pages/apply-stylesheet.adoc deleted file mode 100644 index e645e664..00000000 --- a/docs/modules/html-backend/pages/apply-stylesheet.adoc +++ /dev/null @@ -1,97 +0,0 @@ -= Apply a Custom Stylesheet -//// -apply-theme.adoc, 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=my-styles.css my-sample.adoc - -. Save your custom stylesheet in the same directory as [.path]_my-sample.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 [.path]_my-sample.adoc_. - -[source,asciidoc] ----- -include::example$mysample-stylesheet.adoc[] ----- - -==== -#fix ex# -//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 [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_. -Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory. - -[source,asciidoc] ----- -include::example$mysample-stylesdir.adoc[] ----- - -After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory. - -==== -#fix ex# -//image::mysample-stylesdir-dir.png[] -==== - -You can also set `stylesdir` in the CLI. - - $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc - -If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`. - -[source,asciidoc] ----- -include::example$mysample-stylesdir-link.adoc[] ----- - -After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ 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-nested] -.Stylesheets and processing multiple nested documents -**** -When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], 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: - -.... -/my-documents - a.adoc - b.adoc - /my-nested-documents - c.adoc - /my-stylesheets -.... - -For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to: - -[source,asciidoc] ----- -:stylesdir: my-stylesheets ----- - -For [.path]_c.adoc_, set `stylesdir` to: - -[source,asciidoc] ----- -:stylesdir: ../my-stylesheets ----- - -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/docs/modules/html-backend/pages/custom-stylesheets.adoc b/docs/modules/html-backend/pages/custom-stylesheets.adoc new file mode 100644 index 00000000..1cc20d2a --- /dev/null +++ b/docs/modules/html-backend/pages/custom-stylesheets.adoc @@ -0,0 +1,97 @@ += Apply a Custom Stylesheet +//// +apply-theme.adoc, 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 xref:manage-stylesheets.adoc[default stylesheet], you can have the output document link to or embed your custom stylesheet. + +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=my-styles.css my-sample.adoc + +. Save your custom stylesheet in the same directory as [.path]_my-sample.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 [.path]_my-sample.adoc_. + +[source,asciidoc] +---- +include::example$mysample-stylesheet.adoc[] +---- + +==== +#fix ex# +//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 [.path]_my-styles.css_ into [.path]_my-documents/my-stylesheets_. +Our AsciiDoc document, [.path]_my-sample.adoc_, is saved in the [.path]_my-documents_ directory. + +[source,asciidoc] +---- +include::example$mysample-stylesdir.adoc[] +---- + +After processing [.path]_my-sample.adoc_, its HTML output ([.path]_my-sample.html_), which includes the embedded [.path]_my-styles.css_ stylesheet, is created in the [.path]_my-documents_ directory. + +==== +#fix ex# +//image::mysample-stylesdir-dir.png[] +==== + +You can also set `stylesdir` in the CLI. + + $ asciidoctor -a stylesdir=my-stylesheets/ -a stylesheet=my-styles.css my-sample.adoc + +If you don't want to embed the [.path]_my-styles.css_ stylesheet into your HTML output, make sure to set `linkcss`. + +[source,asciidoc] +---- +include::example$mysample-stylesdir-link.adoc[] +---- + +After your document is converted, notice that a copy of [.path]_my-styles.css_ was not created in the [.path]_my-documents_ 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-nested] +.Stylesheets and processing multiple nested documents +**** +When you are xref:cli:process-multiple-files.adoc[running Asciidoctor once across a nested set of documents], 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: + +.... +/my-documents + a.adoc + b.adoc + /my-nested-documents + c.adoc + /my-stylesheets +.... + +For [.path]_a.adoc_ and [.path]_b.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: my-stylesheets +---- + +For [.path]_c.adoc_, set `stylesdir` to: + +[source,asciidoc] +---- +:stylesdir: ../my-stylesheets +---- + +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/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc index 5c562bdb..be3c9ec3 100644 --- a/docs/modules/html-backend/pages/index.adoc +++ b/docs/modules/html-backend/pages/index.adoc @@ -9,7 +9,7 @@ Asciidoctor's default output format is HTML. == Generate HTML using the html5 converter -In this section, we'll create a sample document, then process and convert it with Asciidoctor's `html5` converter. +In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter. . Create an AsciiDoc file like the one below . Save the file as [.path]_my-sample.adoc_ diff --git a/docs/modules/html-backend/pages/manage-stylesheets.adoc b/docs/modules/html-backend/pages/manage-stylesheets.adoc index aa6042b3..781c736e 100644 --- a/docs/modules/html-backend/pages/manage-stylesheets.adoc +++ b/docs/modules/html-backend/pages/manage-stylesheets.adoc @@ -3,13 +3,12 @@ == What is the default stylesheet? Asciidoctor comes bundled with a stylesheet, named [.path]_asciidoctor.css_. -It uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes. -This stylesheet is applied by default unless you tell Asciidoctor to use another stylesheet. -See xref:html-backend:apply-stylesheet.adoc[] to learn about the default and custom stylesheet options. +The built-in HTML converter uses this stylesheet for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes. +Asciidoctor applies this stylesheet by default unless you tell Asciidoctor to use another stylesheet. == Embed a stylesheet -When you generate a document with the `html5` backend, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the safe mode is less than `SECURE`. +When you generate a document using the built-in HTML converter, the [.path]_asciidoctor.css_ stylesheet is embedded into the HTML output by default when the xref:ROOT:safe-modes.adoc[safe mode] is less than `SECURE`. If your stylesheet is being linked to when you expect it to be embedded, lower the safe mode (`safe` is the recommend value). == Link to a stylesheet @@ -37,10 +36,10 @@ Additionally, you can inspect [.path]_my-sample.html_ in your browser and see `< //image::mysample-link.png[] ==== -== Don't apply a stylesheet +== Disable a stylesheet If you don't want any styles applied to the HTML output of your document, unset the `stylesheet` attribute. $ asciidoctor -a stylesheet! my-sample.adoc -One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:apply-stylesheet.adoc[custom stylesheet]. +One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own xref:custom-stylesheets.adoc[custom stylesheet]. diff --git a/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc new file mode 100644 index 00000000..0b9ad08a --- /dev/null +++ b/docs/modules/html-backend/pages/source-highlighting-stylesheets.adoc @@ -0,0 +1,27 @@ += Embed a CodeRay or Pygments Stylesheet +// um anchor: hl-css +// html-code-styles.adoc, included in convert-documents and the user-manual. + +Asciidoctor can embed the stylesheet for the CodeRay or Pygments syntax highlighters. + +== Requirements + +First, make sure the appropriate library is installed on your system. +See xref:source-highlighters:rouge.adoc[], xref:source-highlighters:coderay.adoc[], or xref:source-highlighters:pygments.adoc[] for installation instructions. +Next, set the xref:asciidoc:verbatim:source-highlighter.adoc[source-highlighter attribute] and assign it the value that corresponds to the library you installed. + +[#coderay] +== CodeRay + +If the `source-highlighter` attribute is `coderay` and the `coderay-css` attribute is `class`, the CodeRay stylesheet is: + +* _embedded_ by default +* _copied_ to the file [.path]_asciidoctor-coderay.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set + +[#pygments] +== Pygments + +If the `source-highlighter` attribute is `pygments` and the `pygments-css` attribute is `class`, the Pygments stylesheet is: + +* _embedded_ by default +* _copied_ to the file [.path]_asciidoctor-pygments.css_ inside the `stylesdir` folder within the output directory if `linkcss` is set diff --git a/docs/modules/integrations/nav.adoc b/docs/modules/integrations/nav.adoc deleted file mode 100644 index b6d8da60..00000000 --- a/docs/modules/integrations/nav.adoc +++ /dev/null @@ -1,9 +0,0 @@ -* Integrations -** xref:syntax-highlighters.adoc[] -*** xref:rouge.adoc[] -*** xref:coderay.adoc[] -*** xref:highlightjs.adoc[] -*** xref:pygments.adoc[] -** xref:stem.adoc[] -*** xref:mathjax.adoc[] -*** xref:asciimath-gem.adoc[] diff --git a/docs/modules/integrations/pages/asciimath-gem.adoc b/docs/modules/integrations/pages/asciimath-gem.adoc deleted file mode 100644 index 5d9e82d7..00000000 --- a/docs/modules/integrations/pages/asciimath-gem.adoc +++ /dev/null @@ -1,39 +0,0 @@ -= AsciiMath RubyGem -:url-asciimath-repo: https://github.com/asciidoctor/AsciiMath - -Asciidoctor's built-in DocBook backend and MathJax aren't compatible, so Asciidoctor must explicitly convert xref:asciidoc:stem:stem.adoc[stem expressions] into something the DocBook toolchain can understand. -Enter the {url-rubygem}/asciimath[AsciiMath RubyGem^]. -AsciiMath converts AsciiMath stem expressions in an AsciiDoc document to MathML and outputs them in a format that DocBook accepts. - -TIP: For more information, see the {url-asciimath-repo}[AsciiMath RubyGem repository^]. - -== Install asciimath gem - -To enable AsciiMath support when converting to DocBook, you need to install the asciimath gem: - - $ gem install asciimath - -== Activate asciimath stem expressions - -To activate AsciiMath, set the `stem` attribute in the document's header and assign it the value `asciimath`. (or by passing the attribute to the command line or API). - -.Set the stem attribute -[source,asciidoc] ----- -= Document Title -:stem: asciimath ----- - -To learn how to create inline and block AsciiMath equations, see xref:asciidoc:stem:stem.adoc[]. - -=== Using AsciiMath with the DocBook toolchain - -If you're generating a PDF from the DocBook output, the MathML produced by the asciimath gem needs to be interpreted and drawn into the PDF. -In the DocBook toolchain, this is handled by JEuclid. - -Fortunately, the toolchain is already configured to use the JEuclid integration. -When the DocBook toolchain generates the PDF, the JEuclid FOP plugin processes any MathML found in the DocBook file, including the expressions transformed from AsciiMath to MathML by the asciimath gem. -As a result, AsciiMath stem expressions in the AsciiDoc file will render as expected in the generated PDF. - -There's no equivalent gem for converting STEM expressions written in LaTeX to MathML. -Instead, you can convert the DocBook to PDF using the dblatex pipeline, which supports LaTeX expressions. diff --git a/docs/modules/integrations/pages/coderay.adoc b/docs/modules/integrations/pages/coderay.adoc deleted file mode 100644 index 7a590b8a..00000000 --- a/docs/modules/integrations/pages/coderay.adoc +++ /dev/null @@ -1,107 +0,0 @@ -= CodeRay -:url-coderay: http://coderay.rubychan.de/ -:url-coderay-gem: https://rubygems.org/gems/coderay - -{url-coderay}[CodeRay^] is an encoding-aware, syntax highlighter that supports the languages listed below. - -[%autowidth,cols="3*",grid=none,frame=none] -|=== -| C -| C++ -| Clojure - -| CSS -| Delphi -| diff - -| ERB -| Go -| Groovy - -| HAML -| HTML -| Java - -| JavaScript -| JSON -| Lua - -| PHP -| Python -| Ruby - -| Sass -| SQL -| Taskpaper - -| XML -| YAML -| -|=== - -== Install CodeRay - -To use CodeRay with Asciidoctor, you need the {url-coderay-gem}[coderay RubyGem^]. -You can use one of the following methods to install CodeRay. - -Install using gem (all systems):: -+ - $ gem install coderay - -Install using apt-get (Debian-based systems):: -+ - $ sudo apt-get install coderay - -Install using dnf (Fedora-based systems):: -+ - $ sudo dnf install rubygem-coderay - -== Activate CodeRay - -Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it. - -[source] ----- -:source-highlighter: coderay ----- - -== CodeRay attributes - -You can further customize the source block output with additional CodeRay attributes. - -coderay-css:: -Controls what method is used for applying CSS to the tokens. -Can be `class` or `style`. -Default: `class`. - -coderay-linenums-mode:: -Controls how line numbers are laid out. -Can be `table` or `inline`. -If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines. -Default: `table`. - -.Customizing a source block with CodeRay line numbers -[source] -.... -:source-highlighter: coderay -:coderay-linenums-mode: inline - -[source,ruby,linenums] ----- -ORDERED_LIST_KEYWORDS = { - 'loweralpha' => 'a', - 'lowerroman' => 'i', - 'upperalpha' => 'A', - 'upperroman' => 'I' - #'lowergreek' => 'a' - #'arabic' => '1' - #'decimal' => '1' -} ----- -.... - -See the xref:html-backend:apply-code-stylesheets.adoc#coderay[CodeRay stylesheet section] to learn about the `coderay-css` attribute. - -//// -Note: I'm not getting this to work. Need to come back and do some quality assurance. -//// diff --git a/docs/modules/integrations/pages/highlightjs.adoc b/docs/modules/integrations/pages/highlightjs.adoc deleted file mode 100644 index 17372031..00000000 --- a/docs/modules/integrations/pages/highlightjs.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= Highlight.js -:url-highlightjs: https://highlightjs.org/ -:url-highlightjs-lang: https://highlightjs.org/download/ -:url-highlightjs-cdn: https://cdnjs.com/libraries/highlight.js - -{url-highlightjs}[Highlight.js^] is a popular client-side syntax highlighter that supports a broad range of {url-highlightjs-lang}[languages^]. - -== Activate highlight.js - -To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file: - -[source] ----- -:source-highlighter: highlight.js ----- - -By default, Asciidoctor will link to the highlight.js library and stylesheet hosted on {url-highlightjs-cdn}[cdnjs^]. -The version of the highlight.js library Asciidoctor loads from the CDN only includes support for languages in the common language bundle (apache, bash, coffeescript, cpp, cs, css, diff, http, ini, java, javascript, json, makefile, markdown, nginx, objectivec, perl, php, properties, python, ruby, shell, sql, xml, and yaml). - -== Load support for additional languages - -To load additional languages supported by highlight.js, list them in the value of the `highlightjs-languages` document attribute (separated by commas): - -[source] ----- -:source-highlighter: highlight.js -:highlightjs-languages: rust, swift ----- - -== Using a custom highlight.js library - -If you'd rather use a personal copy of highlight.js instead of the one hosted on the CDN, follow these steps: - -. Create your custom bundle on the {url-highlightjs-lang}[download page^]. -. Download and unpack the zip into a folder called [.path]_highlight_ adjacent to your AsciiDoc file (or in the output directory, if different) -. Rename [.path]_highlight/highlight.pack.js_ to [.path]_highlight/highlight.min.js_ -. Rename [.path]_highlight/styles/github.css_ to [.path]_highlight/styles/github.min.css_ -** Replace `github` with the name of the `highlightjs-theme` you are using, if different. -. Add the attribute entry `:highlightjsdir: highlight` to the header of your AsciiDoc file. -** Alternatively, you can pass the `-a highlightjsdir=highlight` flag when invoking the Asciidoctor CLI. - -The output file will use your personal copy of the highlight.js library and stylesheet instead of the one hosted on cdnjs. diff --git a/docs/modules/integrations/pages/mathjax.adoc b/docs/modules/integrations/pages/mathjax.adoc deleted file mode 100644 index b27c7928..00000000 --- a/docs/modules/integrations/pages/mathjax.adoc +++ /dev/null @@ -1,7 +0,0 @@ -= MathJax -:url-mathjax: https://www.mathjax.org -:url-asciimath: https://docs.mathjax.org/en/latest/input/asciimath.html -:url-latexmath: https://docs.mathjax.org/en/latest/input/tex/index.html - -{url-mathjax}[MathJax^] is a JavaScript library for displaying Science, Technology, Engineering and Math (STEM) expressions in the browser. -The Asciidoctor HTML backend relies on MathJax to parse and render {url-asciimath}[AsciiMath^] and {url-latexmath}[TeX and LaTeX^] math notation. diff --git a/docs/modules/integrations/pages/pygments.adoc b/docs/modules/integrations/pages/pygments.adoc deleted file mode 100644 index 9456955b..00000000 --- a/docs/modules/integrations/pages/pygments.adoc +++ /dev/null @@ -1,156 +0,0 @@ -= Pygments -:url-pygments: https://pygments.org -:url-pygments-lang: https://pygments.org/languages/ -:url-python: https://www.python.org -:url-pygments-gem: https://rubygems.org/gems/pygments.rb - -{url-pygments}[Pygments^] is a popular syntax highlighter that supports a broad range of {url-pygments-lang}[programming and template languages^]. - -== Install Pygments - -In order to use Pygments with Asciidoctor, you need {url-python}[Python 2^] and the {url-pygments-gem}[pygments.rb gem^]. -The pygments.rb gem manages calls to Pygments, which is an external program that runs using Python. - -TIP: You do not need to install Pygments itself. -It comes bundled with the pygments.rb gem. - -IMPORTANT: You must have Python 2 installed to use pygments.rb. -Python 3 is not compatible with the pygments.rb gem. -Check that you have a `python2` (Linux), `python` (macOS), or `py -2` (Windows) executable on your PATH. -(On macOS, verify that the `python` executable uses Python 2 by running `python -V`). - -.Installing Python and the pygments.rb gem via the CLI (cross platform) -[source,console] -.... -$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python # <.> -$ gem install pygments.rb # <.> -.... -<.> Install Python using your package manager -<.> Install the pygments.rb gem - -== Activate Pygments - -Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header. - -[source] ----- -:source-highlighter: pygments ----- - -== Pygments attributes - -You can further customize the source block output with additional Pygments attributes. - -pygments-style:: -Sets the name of the color theme Pygments uses. -To see the list of available style names, see <>. -Default: `pastie`. - -pygments-css:: -Controls what method is used for applying CSS to the tokens. -Can be `class` (CSS classes) or `style` (inline styles). -See the xref:html-backend:apply-code-stylesheets.adoc#pygments[Pygments stylesheet section] to learn more about how the value `class` is handled. -Default: `class`. - -pygments-linenums-mode:: -Controls how line numbers are arranged when line numbers are enabled on the source block. -Can be `table` or `inline`. -If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines. -Default: `table`. - -.Customizing a source block with Pygments attributes -[source] -.... -:source-highlighter: pygments -:pygments-style: manni -:pygments-linenums-mode: inline - -[source,ruby,linenums] ----- -ORDERED_LIST_KEYWORDS = { - 'loweralpha' => 'a', - 'lowerroman' => 'i', - 'upperalpha' => 'A', - 'upperroman' => 'I' - #'lowergreek' => 'a' - #'arabic' => '1' - #'decimal' => '1' -} ----- -.... - -//// -.Result: Source block using inline line numbers and the manni theme -==== -image::custom-pygments.png[Line numbers and a custom Pygments theme for a source block.] -==== -//// - -[#listing-pygments-style-names] -=== Available Pygments style names - -To list the available Pygments styles, run the following command in a terminal: - - $ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles - -The pygments.rb gem uses a bundled version of Pygments (often ahead of the latest release). -This command ensures that you are invoking the `pygmentize` command from the Pygments used by that gem. - -== Pygments timeout - -Since Pygments is an external program, the call to that command is managed by a timeout to safe-guard against a hanging process. -By default, this timeout is 8 seconds. -If you discover that the call is failing to complete within this timeout period, you can increase the timeout (in seconds) by setting the `MENTOS_TIMEOUT` environment variable. - - export MENTOS_TIMEOUT=30 - -Now the call to Pygments will be allocated up to 30 seconds to complete. - -== Using a custom Pygments installation - -If you already have Pygments installed on your system, you want to use your own fork, or you want to customize how Pygments is configured, you can get Asciidoctor to use a custom version of Pygments instead of the one bundled with the pygments.rb gem. - -First, install your own version of Pygments. -You can do this, for instance, by cloning the upstream Pygments repository: - - $ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments - -Find the directory that contains the file [.path]_pygmentize_ or the [.path]_Makefile_. -That's your Pygments installation path. -Make note of it. - -Next, create a script to run _before_ invoking Asciidoctor for the first time. -Let's call it [.path]_pygments_init.rb_. -Populate the script with the following content: - -.pygments_init.rb -[source,ruby] ----- -require 'pygments' - -# use a custom Pygments installation (directory that contains pygmentize) -Pygments.start '/path/to/pygments' - -# example of registering a missing or additional lexer -#Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'], -# filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle'] ----- - -TIP: You could enhance this script to read the Pygments installation path from an environment variable (or configuration file). - -Now just require this script before your invoke Asciidoctor the first time. -When using the `asciidoctor` command, pass the script using the `-r` flag: - - $ asciidoctor -r ./pygments_init.rb document.adoc - -When using the Asciidoctor API, require the script using `require` or `require_relative`: - -[source,ruby] ----- -require 'asciidoctor' -require_relative './pygments_init.rb' - -Asciidoctor.convert_file 'document.adoc', safe: :safe ----- - -Now Asciidoctor is using your custom installation of Pygments instead of the one bundled with the pygments.rb gem. diff --git a/docs/modules/integrations/pages/rouge.adoc b/docs/modules/integrations/pages/rouge.adoc deleted file mode 100644 index b6022864..00000000 --- a/docs/modules/integrations/pages/rouge.adoc +++ /dev/null @@ -1,70 +0,0 @@ -= Rouge -:url-rouge: http://rouge.jneen.net -:url-rouge-gem: https://rubygems.org/gems/rouge -:url-rouge-repo: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes - -{url-rouge}[Rouge^] is an extendable code highlighter written in Ruby that supports a vast array of languages. - -== Install Rouge - -To use Rouge with Asciidoctor, you need the {url-rouge-gem}[rouge RubyGem^]. -You can use one of the following methods to install Rouge. - -Install using `gem` (all systems):: -+ - $ gem install rouge - -Install using `apt-get` (Debian-based systems):: -+ - $ sudo apt-get install rouge - -Install using `dnf` (Fedora-based systems):: -+ - $ sudo dnf install rubygem-rouge - -== Assign rouge to source-highlighter - -Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it. - -[source] ----- -:source-highlighter: rouge ----- - -== Rouge attributes - -You can further customize the source block output with additional Rouge attributes. - -rouge-css:: -Controls what method is used for applying CSS to the tokens. -Can be `class` or `style`. -Default: `class`. - -[.line-through]#rouge-linenums-mode# (not currently implemented):: -Controls how line numbers are laid out. -Can be `table` or `inline`. -If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines. -Default: `table`. - -rouge-style:: -Controls the color theme used to for highlighting. -You can find the list of themes in the {url-rouge-repo}[Rouge code repository^]. - -.Customizing a source block with Rouge line numbers -[source] -.... -:source-highlighter: rouge - -[source,ruby,linenums] ----- -ORDERED_LIST_KEYWORDS = { - 'loweralpha' => 'a', - 'lowerroman' => 'i', - 'upperalpha' => 'A', - 'upperroman' => 'I' - #'lowergreek' => 'a' - #'arabic' => '1' - #'decimal' => '1' -} ----- -.... diff --git a/docs/modules/integrations/pages/stem.adoc b/docs/modules/integrations/pages/stem.adoc deleted file mode 100644 index 809dfa16..00000000 --- a/docs/modules/integrations/pages/stem.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Supported STEM Libraries -// Stem equations and formulas - -[%autowidth] -|=== -|Integration |Supported Versions |Backends - -|MathJax -|2.7.9 -|HTML - -|AsciiMath -|2.0.x -|Docbook -|=== diff --git a/docs/modules/integrations/pages/syntax-highlighters.adoc b/docs/modules/integrations/pages/syntax-highlighters.adoc deleted file mode 100644 index a8354393..00000000 --- a/docs/modules/integrations/pages/syntax-highlighters.adoc +++ /dev/null @@ -1,26 +0,0 @@ -= Supported Syntax Highlighters - -[%autowidth] -|=== -|Feature |Supported Integration |Supported Versions - -|Client-side syntax highlighting for source code blocks -|Highlight.js -|9.18.3 - -.3+|Server-side syntax highlighting for source code blocks -|CodeRay -|1.1.2 - -|Pygments -|2.2.0 - -|Rouge -|3.1.1 -|=== - -//// -|Inline, admonition or callout font-based icons -|Font Awesome -|4.7 -//// diff --git a/docs/modules/manpage-backend/pages/index.adoc b/docs/modules/manpage-backend/pages/index.adoc index 31386990..346fa25a 100644 --- a/docs/modules/manpage-backend/pages/index.adoc +++ b/docs/modules/manpage-backend/pages/index.adoc @@ -1,5 +1,5 @@ -= Generate Man Pages from AsciiDoc -:navtitle: Generate Man Pages += Generate Manual Pages from AsciiDoc +:navtitle: Generate Manual Pages :url-man7: https://man7.org/linux/man-pages/man7/roff.7.html :url-docbook-refmisc: https://tdg.docbook.org/tdg/5.0/refmiscinfo.html :url-manpage-raw: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc @@ -11,11 +11,11 @@ Asciidoctor's built-in man page converter generates {url-man7}[roff-formatted^] == What is a manual page? A manual page, often abbreviated to man page, is a form of software documentation found on Unix-based operating systems. -The formalized structure of its content allows the `man` command to present the man page as a formatted document in a terminal pager. +The formalized structure of its content allows the `man` command to present the manual page as a formatted document in a terminal pager. == Generate a man page with the manpage converter -Before running Asciidoctor, make sure your source document adheres to the <> and has the doctype attribute set to `manpage`. +Before running Asciidoctor, make sure your source document adheres to the <> and the `doctype` attribute is assigned the value `manpage`. To generate a man page, run: @@ -42,6 +42,7 @@ Here is an example man page composed in AsciiDoc for the `eve` command: include::example$manpage.adoc[] ---- +[#doctype] == Man page doctype The `manpage` doctype has the following required parts: @@ -66,51 +67,51 @@ Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`B Several built-in document attributes only affect man pages. These attributes must be set in the document header. -[cols="<15,<30,<30"] -.Built-in document attributes specific to the manpage doctype +.Built-in manpage document attributes +[%autowidth] |=== -|Attribute name |Description |Value (as parsed from example above) +|Attribute |Description |Value (as parsed from example above) -|mantitle +|`mantitle` |Alternative way to set the man page name. |ASCIIDOCTOR(1) -|manvolnum +|`manvolnum` |Manual section number. |1 -|manname +|`manname` |Alternative way to set the command name. |asciidoctor -|manpurpose +|`manpurpose` |Alternative way to set the command purpose. |converts AsciiDoc source files -|man-linkstyle +|`man-linkstyle` |Style the links in the manpage output. A valid link format sequence. // Needs a reference to this. |blue R <> -|mansource +|`mansource` |The source to which the manpage pertains. When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer. |Asciidoctor -|manversion +|`manversion` |The version of the man page. Defaults to revnumber if not specified. When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer. Not used by Asciidoctor. |1.5.4 -|manmanual +|`manmanual` |Manual name. When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer. |Asciidoctor Manual |=== Refer to {url-manpage-raw}[the AsciiDoc source of the Asciidoctor man page^] to see a complete example. -The man page for Asciidoctor is produced using the `manpage` converter. -The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow. +The manual page for Asciidoctor is produced using the `manpage` converter. +The manual pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow. diff --git a/docs/modules/migrate/pages/asciidoc-python.adoc b/docs/modules/migrate/pages/asciidoc-python.adoc index c18e26c4..56d4b608 100644 --- a/docs/modules/migrate/pages/asciidoc-python.adoc +++ b/docs/modules/migrate/pages/asciidoc-python.adoc @@ -294,7 +294,7 @@ a| === Custom extensions AsciiDoc.py custom extensions are Python commands, so they don't work with Asciidoctor. -Depending on the Asciidoctor processor you choose, you can re-write your xref:extensions:register.adoc[extensions in Ruby, Java, or JavaScript]. +Depending on the Asciidoctor processor you choose, you can re-write your xref:extensions:index.adoc[extensions in Ruby, Java, or JavaScript]. == Doctest diff --git a/docs/modules/source-highlighters/nav.adoc b/docs/modules/source-highlighters/nav.adoc new file mode 100644 index 00000000..7464bc7e --- /dev/null +++ b/docs/modules/source-highlighters/nav.adoc @@ -0,0 +1,5 @@ +* xref:index.adoc[] +** xref:highlightjs.adoc[] +** xref:rouge.adoc[] +** xref:coderay.adoc[] +** xref:pygments.adoc[] diff --git a/docs/modules/source-highlighters/pages/coderay.adoc b/docs/modules/source-highlighters/pages/coderay.adoc new file mode 100644 index 00000000..c7b035a9 --- /dev/null +++ b/docs/modules/source-highlighters/pages/coderay.adoc @@ -0,0 +1,107 @@ += CodeRay +:url-coderay: http://coderay.rubychan.de/ +:url-coderay-gem: https://rubygems.org/gems/coderay + +{url-coderay}[CodeRay^] is an encoding-aware, syntax highlighter that supports the languages listed below. + +[%autowidth,cols="3*",grid=none,frame=none] +|=== +| C +| C++ +| Clojure + +| CSS +| Delphi +| diff + +| ERB +| Go +| Groovy + +| HAML +| HTML +| Java + +| JavaScript +| JSON +| Lua + +| PHP +| Python +| Ruby + +| Sass +| SQL +| Taskpaper + +| XML +| YAML +| +|=== + +== Install CodeRay + +To use CodeRay with Asciidoctor, you need the {url-coderay-gem}[coderay RubyGem^]. +You can use one of the following methods to install CodeRay. + +Install using gem (all systems):: ++ + $ gem install coderay + +Install using apt-get (Debian-based systems):: ++ + $ sudo apt-get install coderay + +Install using dnf (Fedora-based systems):: ++ + $ sudo dnf install rubygem-coderay + +== Activate CodeRay + +Once you've installed the RubyGem, assign the `coderay` value to the `source-highlighter` attribute in the document header to activate it. + +[source] +---- +:source-highlighter: coderay +---- + +== CodeRay attributes + +You can further customize the source block output with additional CodeRay attributes. + +coderay-css:: +Controls what method is used for applying CSS to the tokens. +Can be `class` or `style`. +Default: `class`. + +coderay-linenums-mode:: +Controls how line numbers are laid out. +Can be `table` or `inline`. +If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines. +Default: `table`. + +.Customizing a source block with CodeRay line numbers +[source] +.... +:source-highlighter: coderay +:coderay-linenums-mode: inline + +[source,ruby,linenums] +---- +ORDERED_LIST_KEYWORDS = { + 'loweralpha' => 'a', + 'lowerroman' => 'i', + 'upperalpha' => 'A', + 'upperroman' => 'I' + #'lowergreek' => 'a' + #'arabic' => '1' + #'decimal' => '1' +} +---- +.... + +See the xref:html-backend:source-highlighting-stylesheets.adoc#coderay[CodeRay stylesheet section] to learn about the `coderay-css` attribute. + +//// +Note: I'm not getting this to work. Need to come back and do some quality assurance. +//// diff --git a/docs/modules/source-highlighters/pages/highlightjs.adoc b/docs/modules/source-highlighters/pages/highlightjs.adoc new file mode 100644 index 00000000..17372031 --- /dev/null +++ b/docs/modules/source-highlighters/pages/highlightjs.adoc @@ -0,0 +1,42 @@ += Highlight.js +:url-highlightjs: https://highlightjs.org/ +:url-highlightjs-lang: https://highlightjs.org/download/ +:url-highlightjs-cdn: https://cdnjs.com/libraries/highlight.js + +{url-highlightjs}[Highlight.js^] is a popular client-side syntax highlighter that supports a broad range of {url-highlightjs-lang}[languages^]. + +== Activate highlight.js + +To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file: + +[source] +---- +:source-highlighter: highlight.js +---- + +By default, Asciidoctor will link to the highlight.js library and stylesheet hosted on {url-highlightjs-cdn}[cdnjs^]. +The version of the highlight.js library Asciidoctor loads from the CDN only includes support for languages in the common language bundle (apache, bash, coffeescript, cpp, cs, css, diff, http, ini, java, javascript, json, makefile, markdown, nginx, objectivec, perl, php, properties, python, ruby, shell, sql, xml, and yaml). + +== Load support for additional languages + +To load additional languages supported by highlight.js, list them in the value of the `highlightjs-languages` document attribute (separated by commas): + +[source] +---- +:source-highlighter: highlight.js +:highlightjs-languages: rust, swift +---- + +== Using a custom highlight.js library + +If you'd rather use a personal copy of highlight.js instead of the one hosted on the CDN, follow these steps: + +. Create your custom bundle on the {url-highlightjs-lang}[download page^]. +. Download and unpack the zip into a folder called [.path]_highlight_ adjacent to your AsciiDoc file (or in the output directory, if different) +. Rename [.path]_highlight/highlight.pack.js_ to [.path]_highlight/highlight.min.js_ +. Rename [.path]_highlight/styles/github.css_ to [.path]_highlight/styles/github.min.css_ +** Replace `github` with the name of the `highlightjs-theme` you are using, if different. +. Add the attribute entry `:highlightjsdir: highlight` to the header of your AsciiDoc file. +** Alternatively, you can pass the `-a highlightjsdir=highlight` flag when invoking the Asciidoctor CLI. + +The output file will use your personal copy of the highlight.js library and stylesheet instead of the one hosted on cdnjs. diff --git a/docs/modules/source-highlighters/pages/index.adoc b/docs/modules/source-highlighters/pages/index.adoc new file mode 100644 index 00000000..4312be25 --- /dev/null +++ b/docs/modules/source-highlighters/pages/index.adoc @@ -0,0 +1,32 @@ += Source Highlighting + +[%autowidth] +|=== +| |Syntax Highlighter |Supported Versions |Converters + +|Client-side highlighting for source code blocks + +|Highlight.js +|9.18.3 +|HTML + +.3+|Server-side highlighting for source code blocks + +|CodeRay +|1.1.2 +|HTML + +|Pygments +|2.2.0 +|HTML + +|Rouge +|3.1.1 +|HTML +|=== + +//// +|Inline, admonition or callout font-based icons +|Font Awesome +|4.7 +//// diff --git a/docs/modules/source-highlighters/pages/pygments.adoc b/docs/modules/source-highlighters/pages/pygments.adoc new file mode 100644 index 00000000..a049b690 --- /dev/null +++ b/docs/modules/source-highlighters/pages/pygments.adoc @@ -0,0 +1,156 @@ += Pygments +:url-pygments: https://pygments.org +:url-pygments-lang: https://pygments.org/languages/ +:url-python: https://www.python.org +:url-pygments-gem: https://rubygems.org/gems/pygments.rb + +{url-pygments}[Pygments^] is a popular syntax highlighter that supports a broad range of {url-pygments-lang}[programming and template languages^]. + +== Install Pygments + +In order to use Pygments with Asciidoctor, you need {url-python}[Python 2^] and the {url-pygments-gem}[pygments.rb gem^]. +The pygments.rb gem manages calls to Pygments, which is an external program that runs using Python. + +TIP: You do not need to install Pygments itself. +It comes bundled with the pygments.rb gem. + +IMPORTANT: You must have Python 2 installed to use pygments.rb. +Python 3 is not compatible with the pygments.rb gem. +Check that you have a `python2` (Linux), `python` (macOS), or `py -2` (Windows) executable on your PATH. +(On macOS, verify that the `python` executable uses Python 2 by running `python -V`). + +.Installing Python and the pygments.rb gem via the CLI (cross platform) +[source,console] +.... +$ "`\which apt-get || \which dnf || \which yum || \which brew`" install python # <.> +$ gem install pygments.rb # <.> +.... +<.> Install Python using your package manager +<.> Install the pygments.rb gem + +== Activate Pygments + +Once you've installed these libraries, assign `pygments` to the `source-highlighter` attribute in your document's header. + +[source] +---- +:source-highlighter: pygments +---- + +== Pygments attributes + +You can further customize the source block output with additional Pygments attributes. + +pygments-style:: +Sets the name of the color theme Pygments uses. +To see the list of available style names, see <>. +Default: `pastie`. + +pygments-css:: +Controls what method is used for applying CSS to the tokens. +Can be `class` (CSS classes) or `style` (inline styles). +See the xref:html-backend:source-highlighting-stylesheets.adoc#pygments[Pygments stylesheet section] to learn more about how the value `class` is handled. +Default: `class`. + +pygments-linenums-mode:: +Controls how line numbers are arranged when line numbers are enabled on the source block. +Can be `table` or `inline`. +If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines. +Default: `table`. + +.Customizing a source block with Pygments attributes +[source] +.... +:source-highlighter: pygments +:pygments-style: manni +:pygments-linenums-mode: inline + +[source,ruby,linenums] +---- +ORDERED_LIST_KEYWORDS = { + 'loweralpha' => 'a', + 'lowerroman' => 'i', + 'upperalpha' => 'A', + 'upperroman' => 'I' + #'lowergreek' => 'a' + #'arabic' => '1' + #'decimal' => '1' +} +---- +.... + +//// +.Result: Source block using inline line numbers and the manni theme +==== +image::custom-pygments.png[Line numbers and a custom Pygments theme for a source block.] +==== +//// + +[#listing-pygments-style-names] +=== Available Pygments style names + +To list the available Pygments styles, run the following command in a terminal: + + $ $(dirname $(gem which pygments.rb))/../vendor/pygments-main/pygmentize -L styles + +The pygments.rb gem uses a bundled version of Pygments (often ahead of the latest release). +This command ensures that you are invoking the `pygmentize` command from the Pygments used by that gem. + +== Pygments timeout + +Since Pygments is an external program, the call to that command is managed by a timeout to safe-guard against a hanging process. +By default, this timeout is 8 seconds. +If you discover that the call is failing to complete within this timeout period, you can increase the timeout (in seconds) by setting the `MENTOS_TIMEOUT` environment variable. + + export MENTOS_TIMEOUT=30 + +Now the call to Pygments will be allocated up to 30 seconds to complete. + +== Using a custom Pygments installation + +If you already have Pygments installed on your system, you want to use your own fork, or you want to customize how Pygments is configured, you can get Asciidoctor to use a custom version of Pygments instead of the one bundled with the pygments.rb gem. + +First, install your own version of Pygments. +You can do this, for instance, by cloning the upstream Pygments repository: + + $ hg clone https://bitbucket.org/birkenfeld/pygments-main pygments + +Find the directory that contains the file [.path]_pygmentize_ or the [.path]_Makefile_. +That's your Pygments installation path. +Make note of it. + +Next, create a script to run _before_ invoking Asciidoctor for the first time. +Let's call it [.path]_pygments_init.rb_. +Populate the script with the following content: + +.pygments_init.rb +[source,ruby] +---- +require 'pygments' + +# use a custom Pygments installation (directory that contains pygmentize) +Pygments.start '/path/to/pygments' + +# example of registering a missing or additional lexer +#Pygments::Lexer.create name: 'Turtle', aliases: ['turtle'], +# filenames: ['*.ttl'], mimetypes: ['text/turtle', 'application/x-turtle'] +---- + +TIP: You could enhance this script to read the Pygments installation path from an environment variable (or configuration file). + +Now just require this script before your invoke Asciidoctor the first time. +When using the `asciidoctor` command, pass the script using the `-r` flag: + + $ asciidoctor -r ./pygments_init.rb document.adoc + +When using the Asciidoctor API, require the script using `require` or `require_relative`: + +[source,ruby] +---- +require 'asciidoctor' +require_relative './pygments_init.rb' + +Asciidoctor.convert_file 'document.adoc', safe: :safe +---- + +Now Asciidoctor is using your custom installation of Pygments instead of the one bundled with the pygments.rb gem. diff --git a/docs/modules/source-highlighters/pages/rouge.adoc b/docs/modules/source-highlighters/pages/rouge.adoc new file mode 100644 index 00000000..b6022864 --- /dev/null +++ b/docs/modules/source-highlighters/pages/rouge.adoc @@ -0,0 +1,70 @@ += Rouge +:url-rouge: http://rouge.jneen.net +:url-rouge-gem: https://rubygems.org/gems/rouge +:url-rouge-repo: https://github.com/rouge-ruby/rouge/tree/master/lib/rouge/themes + +{url-rouge}[Rouge^] is an extendable code highlighter written in Ruby that supports a vast array of languages. + +== Install Rouge + +To use Rouge with Asciidoctor, you need the {url-rouge-gem}[rouge RubyGem^]. +You can use one of the following methods to install Rouge. + +Install using `gem` (all systems):: ++ + $ gem install rouge + +Install using `apt-get` (Debian-based systems):: ++ + $ sudo apt-get install rouge + +Install using `dnf` (Fedora-based systems):: ++ + $ sudo dnf install rubygem-rouge + +== Assign rouge to source-highlighter + +Once you've installed the RubyGem, assign the `rouge` value to the `source-highlighter` attribute in the document header to activate it. + +[source] +---- +:source-highlighter: rouge +---- + +== Rouge attributes + +You can further customize the source block output with additional Rouge attributes. + +rouge-css:: +Controls what method is used for applying CSS to the tokens. +Can be `class` or `style`. +Default: `class`. + +[.line-through]#rouge-linenums-mode# (not currently implemented):: +Controls how line numbers are laid out. +Can be `table` or `inline`. +If line wrapping is enabled on preformatted blocks (i.e., `prewrap`), and you want to use line numbering on source blocks, you must set the value of this attribute to `inline` in order for the numbers to line up properly with their target lines. +Default: `table`. + +rouge-style:: +Controls the color theme used to for highlighting. +You can find the list of themes in the {url-rouge-repo}[Rouge code repository^]. + +.Customizing a source block with Rouge line numbers +[source] +.... +:source-highlighter: rouge + +[source,ruby,linenums] +---- +ORDERED_LIST_KEYWORDS = { + 'loweralpha' => 'a', + 'lowerroman' => 'i', + 'upperalpha' => 'A', + 'upperroman' => 'I' + #'lowergreek' => 'a' + #'arabic' => '1' + #'decimal' => '1' +} +---- +.... diff --git a/docs/modules/stem/nav.adoc b/docs/modules/stem/nav.adoc new file mode 100644 index 00000000..4f96cb52 --- /dev/null +++ b/docs/modules/stem/nav.adoc @@ -0,0 +1,3 @@ +* xref:index.adoc[] +** xref:mathjax.adoc[] +** xref:asciimath-gem.adoc[] diff --git a/docs/modules/stem/pages/asciimath-gem.adoc b/docs/modules/stem/pages/asciimath-gem.adoc new file mode 100644 index 00000000..5d9e82d7 --- /dev/null +++ b/docs/modules/stem/pages/asciimath-gem.adoc @@ -0,0 +1,39 @@ += AsciiMath RubyGem +:url-asciimath-repo: https://github.com/asciidoctor/AsciiMath + +Asciidoctor's built-in DocBook backend and MathJax aren't compatible, so Asciidoctor must explicitly convert xref:asciidoc:stem:stem.adoc[stem expressions] into something the DocBook toolchain can understand. +Enter the {url-rubygem}/asciimath[AsciiMath RubyGem^]. +AsciiMath converts AsciiMath stem expressions in an AsciiDoc document to MathML and outputs them in a format that DocBook accepts. + +TIP: For more information, see the {url-asciimath-repo}[AsciiMath RubyGem repository^]. + +== Install asciimath gem + +To enable AsciiMath support when converting to DocBook, you need to install the asciimath gem: + + $ gem install asciimath + +== Activate asciimath stem expressions + +To activate AsciiMath, set the `stem` attribute in the document's header and assign it the value `asciimath`. (or by passing the attribute to the command line or API). + +.Set the stem attribute +[source,asciidoc] +---- += Document Title +:stem: asciimath +---- + +To learn how to create inline and block AsciiMath equations, see xref:asciidoc:stem:stem.adoc[]. + +=== Using AsciiMath with the DocBook toolchain + +If you're generating a PDF from the DocBook output, the MathML produced by the asciimath gem needs to be interpreted and drawn into the PDF. +In the DocBook toolchain, this is handled by JEuclid. + +Fortunately, the toolchain is already configured to use the JEuclid integration. +When the DocBook toolchain generates the PDF, the JEuclid FOP plugin processes any MathML found in the DocBook file, including the expressions transformed from AsciiMath to MathML by the asciimath gem. +As a result, AsciiMath stem expressions in the AsciiDoc file will render as expected in the generated PDF. + +There's no equivalent gem for converting STEM expressions written in LaTeX to MathML. +Instead, you can convert the DocBook to PDF using the dblatex pipeline, which supports LaTeX expressions. diff --git a/docs/modules/stem/pages/index.adoc b/docs/modules/stem/pages/index.adoc new file mode 100644 index 00000000..6ea72af6 --- /dev/null +++ b/docs/modules/stem/pages/index.adoc @@ -0,0 +1,14 @@ += STEM Processing + +[%autowidth] +|=== +|Integration |Supported Versions |Converters + +|MathJax +|2.7.9 +|HTML + +|AsciiMath +|2.0.x +|Docbook +|=== diff --git a/docs/modules/stem/pages/mathjax.adoc b/docs/modules/stem/pages/mathjax.adoc new file mode 100644 index 00000000..b27c7928 --- /dev/null +++ b/docs/modules/stem/pages/mathjax.adoc @@ -0,0 +1,7 @@ += MathJax +:url-mathjax: https://www.mathjax.org +:url-asciimath: https://docs.mathjax.org/en/latest/input/asciimath.html +:url-latexmath: https://docs.mathjax.org/en/latest/input/tex/index.html + +{url-mathjax}[MathJax^] is a JavaScript library for displaying Science, Technology, Engineering and Math (STEM) expressions in the browser. +The Asciidoctor HTML backend relies on MathJax to parse and render {url-asciimath}[AsciiMath^] and {url-latexmath}[TeX and LaTeX^] math notation. -- cgit v1.2.3