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/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 ++++++ 7 files changed, 132 insertions(+), 133 deletions(-) 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 (limited to 'docs/modules/html-backend') 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 -- cgit v1.2.3