diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..ac67bc74 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,30 @@ +name: Docs + +on: + push: + branches: + - master + pull_request: + branches: + - '*' + +jobs: + lint: + runs-on: 'ubuntu-latest' + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Install Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '2.7' + - name: Install asciidoctor gem + run: | + gem install asciidoctor + - name: Install Vale + run: | + curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v2.6.8 + export PATH="./bin:$PATH" + - name: Lint + run: | + ./bin/vale docs/** diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..c4c28ebb --- /dev/null +++ b/.vale.ini @@ -0,0 +1,14 @@ +# Vale configuration file. +# +# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration. + +StylesPath = docs/.vale +MinAlertLevel = suggestion +WordTemplate = \s(?:%s)\s + +[*] +BlockIgnores = (?s) (\+{4,}.*?\+{4,}) +TokenIgnores = (\$+[^\n$]+\$+) + +[*.adoc] +BasedOnStyles = asciidoctor diff --git a/docs/.vale/asciidoctor/FirstPerson.yml b/docs/.vale/asciidoctor/FirstPerson.yml new file mode 100644 index 00000000..28c057ed --- /dev/null +++ b/docs/.vale/asciidoctor/FirstPerson.yml @@ -0,0 +1,16 @@ +--- +# Warning: asciidoctor.FirstPerson +# +# Checks for use of first person pronouns. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: '"%s" is a first-person pronoun. Use second- or third-person pronouns (like we, you, us, one) instead.' +level: warning +ignorecase: true +scope: paragraph +tokens: + - '\bI[ ,;:?!"]|\bI\x27.{1,2}' + - me + - myself + - mine diff --git a/docs/.vale/asciidoctor/InclusionCultural.yml b/docs/.vale/asciidoctor/InclusionCultural.yml new file mode 100644 index 00000000..5dda8907 --- /dev/null +++ b/docs/.vale/asciidoctor/InclusionCultural.yml @@ -0,0 +1,15 @@ +--- +# Warning: asciidoctorInclusionCultural +# +# Suggests alternatives for words that are culturally inappropriate. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use inclusive language. Consider "%s" instead of "%s".' +level: warning +ignorecase: true +swap: + blacklist(?:ed|ing|s)?: denylist + whitelist(?:ed|ing|s)?: allowlist + \smaster: primary, main + slave: secondary diff --git a/docs/.vale/asciidoctor/InclusionGender.yml b/docs/.vale/asciidoctor/InclusionGender.yml new file mode 100644 index 00000000..3f89b728 --- /dev/null +++ b/docs/.vale/asciidoctor/InclusionGender.yml @@ -0,0 +1,17 @@ +--- +# Suggestion: asciidoctor.InclusionGender +# +# Suggests alternatives for words that are gender-specific. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use inclusive language. Consider "%s" instead of "%s".' +level: suggestion +ignorecase: true +swap: + mankind: humanity, people + manpower: GitLab team members + he: they + his: their + she: they + hers: their diff --git a/docs/.vale/asciidoctor/Repetition.yml b/docs/.vale/asciidoctor/Repetition.yml new file mode 100644 index 00000000..4e3a147c --- /dev/null +++ b/docs/.vale/asciidoctor/Repetition.yml @@ -0,0 +1,12 @@ +--- +# Error: asciidoctor.Repetition +# +# Checks for duplicate words, like `the the` or `and and`. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: repetition +message: '"%s" is repeated.' +level: error +alpha: true +tokens: + - '[^\s]+' diff --git a/docs/.vale/asciidoctor/SentenceLength.yml b/docs/.vale/asciidoctor/SentenceLength.yml new file mode 100644 index 00000000..0cb39a33 --- /dev/null +++ b/docs/.vale/asciidoctor/SentenceLength.yml @@ -0,0 +1,12 @@ +--- +# Warning: asciidoctor.SentenceLength +# +# Counts words in a sentence and alerts if a sentence exceeds 25 words. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: occurrence +message: 'Shorter sentences improve readability (max 25 words).' +scope: sentence +level: warning +max: 25 +token: \b(\w+)\b diff --git a/docs/.vale/asciidoctor/SentenceSpacing.yml b/docs/.vale/asciidoctor/SentenceSpacing.yml new file mode 100644 index 00000000..53d96ce7 --- /dev/null +++ b/docs/.vale/asciidoctor/SentenceSpacing.yml @@ -0,0 +1,16 @@ +--- +# Error: asciidoctor.SentenceSpacing +# +# Checks for the following in common content scenarios: +# +# - No spaces. +# - More than one space. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: '"%s" must contain one and only one space.' +level: error +nonword: true +tokens: + - '[a-z][.?!,][A-Z]' + - '[\w.?!,\(\)\-":] {2,}[\w.?!,\(\)\-":]' diff --git a/docs/.vale/asciidoctor/Simplicity.yml b/docs/.vale/asciidoctor/Simplicity.yml new file mode 100644 index 00000000..b64b4b7a --- /dev/null +++ b/docs/.vale/asciidoctor/Simplicity.yml @@ -0,0 +1,16 @@ +--- +# Suggestion: asciidoctor.Simplicity +# +# Checks for words implying ease of use, to avoid cognitive dissonance for frustrated users. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.' +level: suggestion +ignorecase: true +tokens: + - easy + - easily + - handy + - simple + - simply diff --git a/docs/.vale/asciidoctor/Spelling.yml b/docs/.vale/asciidoctor/Spelling.yml new file mode 100644 index 00000000..271afecd --- /dev/null +++ b/docs/.vale/asciidoctor/Spelling.yml @@ -0,0 +1,17 @@ +--- +# Warning: asciidoctor.Spelling +# +# Checks for possible spelling mistakes in content, not code. May find false positives +# due to links using angle brackets: . These can be ignored. +# +# If a word is flagged as a spelling mistake incorrectly, such as a product name, +# you can submit an PR to update `spelling-exceptions.txt` with the missing word. +# Commands, like `git clone` must use backticks, and must not be added to the +# exceptions. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: spelling +message: 'Spelling check: "%s"?' +level: warning +ignore: + - asciidoctor/spelling-exceptions.txt diff --git a/docs/.vale/asciidoctor/Substitutions.yml b/docs/.vale/asciidoctor/Substitutions.yml new file mode 100644 index 00000000..81f608a0 --- /dev/null +++ b/docs/.vale/asciidoctor/Substitutions.yml @@ -0,0 +1,27 @@ +--- +# Error: asciidoctor.Substitutions +# +# Checks for use of some of the top misused terms in the Asciidoctor community. +# For substitutions only flagged as warnings, see SubstitutionWarning.yml +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use "%s" instead of "%s".' +level: error +ignorecase: true +nonword: false +scope: text +swap: + asciidoctorj: AsciidoctorJ + asciidoctor-reveal.js: Asciidoctor reveal.js + reveal.js: reveal.js + netlify: Netlify + bundler: Bundler + javascript: JavaScript + node: Node + node.js: Node.js + npm: npm + '[^\.-]js': JS + ruby: Ruby + asciidoc: AsciiDoc + asciidoctor: Asciidoctor diff --git a/docs/.vale/asciidoctor/SubstitutionsWarning.yml b/docs/.vale/asciidoctor/SubstitutionsWarning.yml new file mode 100644 index 00000000..faee12ed --- /dev/null +++ b/docs/.vale/asciidoctor/SubstitutionsWarning.yml @@ -0,0 +1,21 @@ +--- +# Warning: asciidoctor.SubstitutionWarning +# +# Warns against using common shorthand for terms. +# For substitutions flagged as errors, see Substitutions.yml +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'If possible, use "%s" instead of "%s".' +link: https://about.gitlab.com/handbook/communication/#top-misused-terms +level: warning +ignorecase: true +swap: + code base: codebase + config: configuration + distro: distribution + file name: filename + filesystem: file system + info: information + repo: repository + utilize: use diff --git a/docs/.vale/asciidoctor/TitleCapitalization.yml b/docs/.vale/asciidoctor/TitleCapitalization.yml new file mode 100644 index 00000000..f181b2da --- /dev/null +++ b/docs/.vale/asciidoctor/TitleCapitalization.yml @@ -0,0 +1,15 @@ +--- +# Warning: asciidoctor.TitleCapitalization +# +# Checks the capitalization for the page title (i.e., doctitle). +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: capitalization +message: "'%s' should be in title case" +level: error +scope: heading.h1 +match: $title +style: Chicago +exceptions: + - npm + - reveal.js diff --git a/docs/.vale/asciidoctor/spelling-exceptions.txt b/docs/.vale/asciidoctor/spelling-exceptions.txt new file mode 100644 index 00000000..e2a4b0bc --- /dev/null +++ b/docs/.vale/asciidoctor/spelling-exceptions.txt @@ -0,0 +1,33 @@ +Asciidoctor +reveal.js +Bundler +gemset +Gemfile +npm +JS +js +JavaScript +Node +toolchain +Netlify +Bilodeau +Moulliard +triaging +prepending +asciidoctor +doctest +html +http +Unversioned +css +docinfo +Docinfo +callout +adoc +https +npx +Dev +prepended +solarized +preloading +preprocessor diff --git a/docs/antora.yml b/docs/antora.yml index af3c7953..909fb0e7 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -9,10 +9,27 @@ nav: asciidoc: attributes: url-project-repo: 'https://github.com/asciidoctor/asciidoctor-reveal.js' - url-project-examples: 'https://github.com/asciidoctor/asciidoctor-reveal.js/blob/master/examples' + url-asciidoctorj-revealjs: 'https://github.com/asciidoctor/asciidoctorj-reveal.js' + url-project-examples: 'https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/examples' + url-project-templates: 'https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates' url-asciidoctor: 'https://github.com/asciidoctor/asciidoctor' url-asciidoctorjs: 'https://github.com/asciidoctor/asciidoctor.js' url-revealjs-home: 'https://revealjs.com' url-revealjs-gh: 'https://github.com/hakimel/reveal.js/blob/v3.9' url-revealjs-doc: 'https://github.com/hakimel/reveal.js/blob/v3.9/README.md' - url-nodejs-download: 'https://nodejs.org/en/download/' + url-nodejs-download: 'https://nodejs.org/en/download' + url-ruby-download: 'https://www.ruby-lang.org/en/downloads' + url-asciidoctor-abstractnode-attr: 'https://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FAbstractNode%3Aattr' + url-slim: 'http://slim-lang.com' + url-rouge: 'http://rouge.jneen.net' + url-pygment: 'https://pygments.org' + url-coderay: 'http://coderay.rubychan.de' + url-bundler: 'https://bundler.io' + url-highlightjs: 'https://highlightjs.org' + url-bulma: 'https://bulma.io' + url-gh-pages: 'https://pages.github.com' + url-netlify: 'https://www.netlify.com' + url-cdnjs: 'https://cdnjs.com' + url-gh-mogztter: 'https://github.com/Mogztter' + url-gh-mojavelinux: 'https://github.com/mojavelinux' + url-gh-graphitefriction: 'https://github.com/graphitefriction' diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index bc23e984..cf58d67d 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -10,4 +10,4 @@ There are four main technology stacks that can convert AsciiDoc into HTML5 / rev * xref:setup:ruby-setup.adoc[Asciidoctor / Ruby / Bundler] * xref:setup:node-js-setup.adoc[Asciidoctor.js / JavaScript (Node.js) / npm] * xref:setup:standalone-executable.adoc[Standalone Executable] -* https://github.com/asciidoctor/asciidoctorj-reveal.js[AsciidoctorJ / JVM / Maven^] +* {url-asciidoctorj-revealjs}[AsciidoctorJ / JVM / Maven^] diff --git a/docs/modules/ROOT/pages/showcase.adoc b/docs/modules/ROOT/pages/showcase.adoc index 01614c2d..1cb70725 100644 --- a/docs/modules/ROOT/pages/showcase.adoc +++ b/docs/modules/ROOT/pages/showcase.adoc @@ -4,7 +4,7 @@ A smooth presentation, featuring video backgrounds, slide transitions, code and callout examples and the use of notes. -https://bentolor.github.io/java9to13/[Presentation] and https://github.com/bentolor/java9to13[source] +https://bentolor.github.io/java9to13/[Presentation^] and https://github.com/bentolor/java9to13[source^] === Screenshots diff --git a/docs/modules/converter/pages/custom-styles.adoc b/docs/modules/converter/pages/custom-styles.adoc index a0210847..c83a1818 100644 --- a/docs/modules/converter/pages/custom-styles.adoc +++ b/docs/modules/converter/pages/custom-styles.adoc @@ -4,7 +4,7 @@ == CSS Override If you use the `:customcss:` document attribute, a CSS file of the name given in the attribute is added to the list of CSS resources loaded by the rendered HTML. -Doing so, you can then easily override specific elements of your theme per presentation. +Doing so, you can then override specific elements of your theme per presentation. For example, to do proper position-independent text placement of a title slide with a specific background you can use: diff --git a/docs/modules/converter/pages/docinfo.adoc b/docs/modules/converter/pages/docinfo.adoc index 236db6d8..5ca9350a 100644 --- a/docs/modules/converter/pages/docinfo.adoc +++ b/docs/modules/converter/pages/docinfo.adoc @@ -2,7 +2,7 @@ :navtitle: Docinfo // Originally from https://github.com/asciidoctor/asciidoctor-bespoke#supplemental-content -It's possible to inject supplemental content into the output document using http://asciidoctor.org/docs/user-manual/#docinfo-file[docinfo files]. +It's possible to inject supplemental content into the output document using xref:asciidoctor:docinfo.adoc[docinfo files]. This core feature of AsciiDoc has been adapted to work with the reveal.js converter. Currently, there are three insertion locations for docinfo content in a reveal.js document: diff --git a/docs/modules/converter/pages/features.adoc b/docs/modules/converter/pages/features.adoc index 4bce3c83..01f05b60 100644 --- a/docs/modules/converter/pages/features.adoc +++ b/docs/modules/converter/pages/features.adoc @@ -54,7 +54,7 @@ See {url-project-repo}/blob/master/examples/concealed-slide-titles.adoc[conceale NOTE: `conceal` and `notitle` have the advantage that the slide still has an id so it can be linked to. IMPORTANT: Like the first page of an AsciiDoc document, the first slide is handled differently. -To hide the whole slide use the `:notitle:` http://asciidoctor.org/docs/user-manual/#header-summary[document attribute]. +To hide the whole slide use the `:notitle:` xref:asciidoc:document:header-ref.adoc[document attribute]. To achieve the effect of hiding only the first slide's title, combine the `:notitle:` attribute on the first slide and use `[%notitle]` on the second slide which will, in effect, be your first slide now. == Content meant for multiple converters diff --git a/docs/modules/converter/pages/revealjs-options.adoc b/docs/modules/converter/pages/revealjs-options.adoc index 26d49bf7..e4530928 100644 --- a/docs/modules/converter/pages/revealjs-options.adoc +++ b/docs/modules/converter/pages/revealjs-options.adoc @@ -1,5 +1,6 @@ = reveal.js Configuration Options :navtitle: Config Options +:experimental: Some attributes can be set at the top of the document that are specific to the `reveal.js` converter. They use the same name as in the `reveal.js` project except that they are prepended by `revealjs_` and case doesn't matter. @@ -22,7 +23,7 @@ Default is disabled. |:highlightjs-theme: | -|Overrides https://highlightjs.org[highlight.js] CSS style with given file or URL. +|Overrides {url-highlightjs}[highlight.js^] CSS style with given file or URL. Default is built-in [path]_lib/css/zenburn.css_. |:revealjsdir: @@ -129,7 +130,7 @@ print:: only show slide numbers when printing to PDF |:revealjs_help: |*true*, false -|Flags if we should show a help overlay when the questionmark key is pressed +|Flags if we should show a help overlay when the question mark key (kbd:[?]) is pressed |:revealjs_showNotes: |*true*, false @@ -137,11 +138,11 @@ print:: only show slide numbers when printing to PDF |:revealjs_autoPlayMedia: |*null*, true, false -a|Global override for autolaying embedded media (video/audio/iframe) +a|Global override for playing automatically embedded media (video/audio/iframe) -null:: Media will only autoplay if data-autoplay is present -true:: All media will autoplay, regardless of individual setting -false:: No media will autoplay, regardless of individual setting +null:: Media will only automatically start to play if data-autoplay is present +true:: All media will automatically start to play, regardless of individual setting +false:: No media will automatically start to play, regardless of individual setting |:revealjs_preloadIframes: |*null*, true, false @@ -282,9 +283,7 @@ Defaults to *1* |=== -If you want to build a custom theme or customize an existing one you should -look at the -{url-revealjs-gh}/css/theme/README.md[reveal.js -theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to -activate it. +If you want to build a custom theme or customize an existing one +you should take a look at the {url-revealjs-gh}/css/theme/README.md[reveal.js theme documentation]. +Then, use the `revealjs_customtheme` AsciiDoc attribute to activate it. diff --git a/docs/modules/converter/pages/revealjs-plugins.adoc b/docs/modules/converter/pages/revealjs-plugins.adoc index 52407a8b..1b78bbe5 100644 --- a/docs/modules/converter/pages/revealjs-plugins.adoc +++ b/docs/modules/converter/pages/revealjs-plugins.adoc @@ -21,7 +21,7 @@ For example, to disable all the default plugins set the following document attri == Additional plugins -Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external javascript files. +Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external JavaScript files. . Extract the plugin files in a directory . Create a JavaScript file that will contain the JavaScript statements to load the plugin (only one required even if you are using several plugins) diff --git a/docs/modules/converter/pages/syntax/admonitions.adoc b/docs/modules/converter/pages/syntax/admonitions.adoc index f6904b15..9b99b527 100644 --- a/docs/modules/converter/pages/syntax/admonitions.adoc +++ b/docs/modules/converter/pages/syntax/admonitions.adoc @@ -1,6 +1,6 @@ = Admonitions -Asciidoctor font-based http://asciidoctor.org/docs/user-manual/#admonition[admonitions] are supported. +Asciidoctor font-based xref:asciidoc:blocks:admonitions.adoc[admonitions] are supported. Make sure to add the following attribute to your document: [source, asciidoc] @@ -17,4 +17,4 @@ Here is an example slide: WARNING: This presentation is dangerous! ---- -Here are details about Asciidoctor's http://asciidoctor.org/docs/user-manual/#admonition-icons[Admonition icons] support. +Here are details about Asciidoctor's xref:asciidoc:blocks:admonitions.adoc#enable-admonition-icons[Admonition icons] support. diff --git a/docs/modules/converter/pages/syntax/background.adoc b/docs/modules/converter/pages/syntax/background.adoc index f39876b3..5b9a826d 100644 --- a/docs/modules/converter/pages/syntax/background.adoc +++ b/docs/modules/converter/pages/syntax/background.adoc @@ -5,7 +5,6 @@ Background colors for slides can be specified by two means: a classic one and one using AsciiDoc roles. See {url-project-repo}/blob/master/examples/background-color.adoc[background-color.adoc] for more examples. - === Using AsciiDoc roles Using roles respects the AsciiDoc philosophy of separation of content and presentation. @@ -100,7 +99,7 @@ For example: ---- See link:{url-revealjs-doc}#video-backgrounds[the relevant reveal.js documentation] for details. -Note that the `data-` prefix is not required in asciidoc files. +Note that the `data-` prefix is not required in AsciiDoc files. == Background iframes diff --git a/docs/modules/converter/pages/syntax/layout.adoc b/docs/modules/converter/pages/syntax/layout.adoc index c52a60bb..d8f2fa54 100644 --- a/docs/modules/converter/pages/syntax/layout.adoc +++ b/docs/modules/converter/pages/syntax/layout.adoc @@ -2,12 +2,12 @@ == Stretch class attribute -reveal.js supports a special class that will give all available screen space to an HTML node. +reveal.js supports a special class that will give all available screen space to an HTML element. This class element is named `stretch`. Sometimes it's desirable to have an element, like an image or video, stretch to consume as much space as possible within a given slide. -To apply that class to block simply use asciidoctor's class assignment: +To add this class to an HTML element, you can assign a role to a block using the shorthand dot (`.`) syntax: [.stretch] @@ -17,23 +17,22 @@ See link:{url-revealjs-doc}#stretching-elements[reveal.js documentation on stret [source,asciidoc] .... -== Slide Six +== Slide 6 Top slide -=== Slide Six.One +=== Slide 6.1 This is a vertical sub-slide .... -Slide Six uses the vertical slide feature of `reveal.js`. -Slide Six.One will be rendered vertically below Slide Six. -Here is link:{url-revealjs-doc}#markup[the relevant reveal.js -documentation] on that topic. +Slide 6 uses the vertical slide feature of `reveal.js`. +Slide 6.1 will be rendered vertically below Slide 6. +Here is link:{url-revealjs-doc}#markup[the relevant reveal.js documentation^] on that topic. == Columns layout -Inspired by https://bulma.io/[Bulma], Asciidoctor reveal.js supports columns layout out-of-the-box: +Inspired by {url-bulma}[Bulma^], Asciidoctor reveal.js supports columns layout out-of-the-box: [source,asciidoc] .... diff --git a/docs/modules/converter/pages/syntax/roles.adoc b/docs/modules/converter/pages/syntax/roles.adoc index 69765b25..660f90b2 100644 --- a/docs/modules/converter/pages/syntax/roles.adoc +++ b/docs/modules/converter/pages/syntax/roles.adoc @@ -23,10 +23,10 @@ Or * Information .... -See https://asciidoctor.org/docs/user-manual/#role[Asciidoctor's documentation] for more details. +See xref:asciidoc:attributes:roles.adoc[Asciidoctor's documentation] for more details. .Image specific note -In addition to the https://asciidoctor.org/docs/user-manual/\#positioning-attributes[existing attributes] to position images, roles can be used as well. However, the shorthand syntax (.) doesn't work in the image macro arguments but must be used above with the angle bracket syntax. +In addition to the xref:asciidoc:macros/image-position.adoc#positioning-attributes[existing attributes] to position images, roles can be used as well. However, the shorthand syntax (.) doesn't work in the image macro arguments but must be used above with the angle bracket syntax. See {url-project-examples}/images.adoc[images.adoc] for examples. Here is a list of supported roles: diff --git a/docs/modules/converter/pages/syntax/syntax-highlighting.adoc b/docs/modules/converter/pages/syntax/syntax-highlighting.adoc index ab7bd306..aa5b4092 100644 --- a/docs/modules/converter/pages/syntax/syntax-highlighting.adoc +++ b/docs/modules/converter/pages/syntax/syntax-highlighting.adoc @@ -1,6 +1,6 @@ = Syntax Highlighting -reveal.js is well integrated with https://highlightjs.org/[Highlight.js] for syntax highlighting. +reveal.js is well integrated with {url-highlightjs}[Highlight.js^] for syntax highlighting. Asciidoctor reveal.js supports that. You can activate Highlight.js syntax highlighting (disabled by default) by setting the `source-highlighter` document attribute as follows: @@ -13,7 +13,7 @@ You can activate Highlight.js syntax highlighting (disabled by default) by setti [NOTE] ==== -By default, we are using a prebuilt version of Highlight.js with 34 commonly used languages hosted on https://cdnjs.com/[cdnjs]. +By default, we are using a prebuilt version of Highlight.js with 34 commonly used languages hosted on {url-cdnjs}[cdnjs]. You can load additional languages using the `:highlightjs-languages:` attribute: [source,asciidoc] @@ -63,7 +63,7 @@ print "$0: hello world\n" ----- [NOTE] -Alternatively, you can use http://rouge.jneen.net/[Rouge], http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as syntax highlighters, +Alternatively, you can use {url-rouge}[Rouge], {url-coderay}[Coderay] or {url-pygment}[Pygments] as syntax highlighters, if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/JavaScript/npm). Check the `examples/` directory for examples and notes about what needs to be done for them to work. -They are considered unsupported by the asciidoctor-reveal.js project. +They are considered unsupported by the Asciidoctor reveal.js project. diff --git a/docs/modules/converter/pages/syntax/title.adoc b/docs/modules/converter/pages/syntax/title.adoc index 92cc67aa..38f29611 100644 --- a/docs/modules/converter/pages/syntax/title.adoc +++ b/docs/modules/converter/pages/syntax/title.adoc @@ -1,7 +1,7 @@ = Title Slide Customization :navtitle: Title Slide -The title slide is customized via Asciidoc attributes. +The title slide is customized via AsciiDoc attributes. These are the global variable assigned at the top of a document under the lead title that look like this: `:name: value`. diff --git a/docs/modules/converter/pages/syntax/video.adoc b/docs/modules/converter/pages/syntax/video.adoc index f9d34c81..d8526cd4 100644 --- a/docs/modules/converter/pages/syntax/video.adoc +++ b/docs/modules/converter/pages/syntax/video.adoc @@ -1,7 +1,7 @@ = Videos In addition to xref:syntax/background.adoc#background_videos[background videos], videos can be inserted directly into slides. -The syntax is the standard http://asciidoctor.org/docs/user-manual/#video[AsciiDoc video block macro] syntax. +The syntax is the standard xref:asciidoc:macros:audio-and-video.adoc#video-macro-syntax[AsciiDoc video block macro] syntax. [source, asciidoc] ---- diff --git a/docs/modules/project/pages/hacking.adoc b/docs/modules/project/pages/hacking.adoc index f0bc65f3..6955752a 100644 --- a/docs/modules/project/pages/hacking.adoc +++ b/docs/modules/project/pages/hacking.adoc @@ -4,8 +4,8 @@ Short instructions that aim to help potential contributors. == Getting Started -* Setup the Asciidoctor-revealjs plugin in <> -* Modify the http://slim-lang.com/[slim templates] in `templates/` +* Setup the Asciidoctor reveal.js plugin in xref:ruby-localversion[development mode] +* Modify the {url-slim}[slim templates^] in `templates/` * Templates need to be compiled before being used, do so with: bundle exec rake build @@ -19,9 +19,9 @@ The next section will provide further help on how to use `print` statements or a == Inspect the template system -To understand what you have access to in templates you can inject some ruby. -With the slim templating system, this is done by prepending the lines with a dash (`-`) and inserting a ruby statement. -Two complementary approaches can be used to explore the context offered by asciidoctor through the template system: +To understand what you have access to in templates you can inject some Ruby. +With the slim templating system, this is done by prepending the lines with a dash (`-`) and inserting a Ruby statement. +Two complementary approaches can be used to explore the context offered by Asciidoctor through the template system: * logging on the command line via print-like statements * jump into the context through an interactive debugger @@ -45,7 +45,7 @@ For example to see which attributes are available, you can print them by adding - puts @document.methods ---- -Other generally useful ruby specific introspection: +Other generally useful Ruby specific introspection: ---- - puts instance_variables @@ -61,8 +61,8 @@ One might find `pp` to produce better output (and in some cases not): === Interactively debug a template -Pry is a powerful debugger for ruby that features tab-completion. -It is very useful to discover a complex object hierarchy like what asciidoctor offers. +Pry is a powerful debugger for Ruby that features tab-completion. +It is very useful to discover a complex object hierarchy like what Asciidoctor offers. ==== Initial Setup @@ -70,7 +70,7 @@ It is very useful to discover a complex object hierarchy like what asciidoctor o ==== Usage -In order to be dropped into the debugger at a specific point in a template simply add the following two lines in the relevant `.slim` template file: +In order to be dropped into the debugger at a specific point in a template add the following two lines in the relevant `.slim` template file: ---- - require 'pry' @@ -101,11 +101,11 @@ From: /home/olivier/src/asciidoc/asciidoctor-reveal.js/templates/slim/section.ht [1] pry(#)> ---- -Then using commands like the following allows you to explore interactively asciidoctor's API and object model with syntax highlighting: +Then using commands like the following allows you to explore interactively Asciidoctor's API and object model with syntax highlighting: [1] pry(#)> @document -You can also query asciidoctor's documentation: +You can also query Asciidoctor's documentation: [4] pry(#)> ? find_by @@ -121,12 +121,12 @@ You can call the slim templates directly with: === References * https://github.com/asciidoctor/asciidoctor.org/issues/80#issuecomment-145698579 -* http://pryrepl.org/ +* https://pry.github.io * http://discuss.asciidoctor.org/Interactively-debugging-a-template-with-a-REPL-td4498.html == Manual Tests -In order to help troubleshoot issues and test syntax improvements, some minimalist asciidoc test files are provided. +In order to help troubleshoot issues and test syntax improvements, some minimalist AsciiDoc test files are provided. You can render the tests files and then load them in a browser and check if `asciidoctor-revealjs` behaves as expected. === Initial Setup @@ -158,9 +158,10 @@ You can open the generated `.html` in `test/doctest/` in a Web browser. == Asciidoctor API's gotchas -=== Attribute inheritence +=== Attribute inheritance -The attr and attr? methods inherit by default. That means if they don't find the attribute defined on the node, they look on the document. +The `attr` and `attr?` methods inherit by default. +That means if they don't find the attribute defined on the Node, they look on the document. You only want to enable inheritance if you intend to allow an attribute of the same name to be controlled globally. That might be good for configuring transitions. For instance: @@ -177,9 +178,9 @@ If that's the case, you generally use the form: attr('name', nil, false) -The second parameter value is the default attribute value, which is nil by default. +The second parameter value is the default attribute value, which is `nil` by default. -Relevant documentation: http://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FAbstractNode%3Aattr +Relevant documentation: {url-asciidoctor-abstractnode-attr} == Merge / Review policy @@ -211,7 +212,7 @@ Early communication often times save time consuming mistakes or avoids duplicate We encourage contributors to communicate with us early. Branches on forks of this project are not very visible to maintainers as much as pull requests (PR). -For this reason we used to recommend sending a PR even if it's not ready and prepend "WIP" in front of its name to let everyone see that you are working on a specific topic. +For this reason we recommend to open a draft PR to let everyone know that you are working on a specific topic. Now, instead of prepending "WIP", we recommend using GitHub "draft pull request" feature instead. @@ -223,16 +224,16 @@ Makes triaging easier. == Node package -=== Test a local asciidoctor-reveal.js version +=== Test locally -In order to test the Node package, you first need to build the converter into Javascript and create a tarball of the project. +In order to test the Node package, you first need to build the converter into JavaScript and create a tarball of the project. $ bundle exec rake build:js $ npm pack That last command will produce a file named `asciidoctor-reveal.js-.tgz` in the working directory. -Then, create a test project adjacent to the clone of the [.path]_asciidoctor-reveal.js_ repository: +Then, create a test project adjacent to the clone of the [.path]`asciidoctor-reveal.js` repository: $ mkdir test-project $ cd test-project @@ -255,14 +256,14 @@ In order for Asciidoctor.js to be able to call code from this converter, the ver Right now we track the exact git revision of Opal used by Asciidoctor.js and make sure that we match. Here is how: -Versions known to work together can be found by looking at the Asciidoctor.js release notes, just replace with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/releases/tag/. +Versions known to work together can be found by looking at the Asciidoctor.js release notes: https://github.com/asciidoctor/asciidoctor.js/releases. Then that Opal version and git revision (if required) must be specified in `asciidoctor-revealjs.gemspec`. -Starting with 3.0.0 we aim to retain binary compatibility between Asciidoctor.js and Asciidoctor-reveal.js. +Starting with 3.0.0, we aim to retain binary compatibility between Asciidoctor.js and Asciidoctor reveal.js. This should allow other Asciidoctor extensions to be called along with this converter. Asciidoctor.js is no longer a direct dependency but should be seen as a tool that powers this converter. We need to allow users to have flexibility in the version they choose to run. -Asciidoctor.js maintainer told us that he is going to consider binary package incompatibility a major break and so we adjusted our README to tell users to install with a specific version range. +Asciidoctor.js maintainers told us that they are going to consider binary package incompatibility a major break and so we adjusted our README to tell users to install with a specific version range. We will track and maintain the README on the major version supported and recommended: @@ -271,7 +272,7 @@ We will track and maintain the README on the major version supported and recomme See https://github.com/asciidoctor/asciidoctor-reveal.js/issues/187#issuecomment-570771473[this issue] for background details on that topic. -Asciidoctor.js versioning policy is https://asciidoctor-docs.netlify.com/asciidoctor.js/project/version-and-lifecycle-policies/[available here]. +Asciidoctor.js versioning policy is xref:asciidoctor.js:project:version-and-lifecycle-policies.adoc[available here]. === Debugging @@ -369,7 +370,7 @@ has been completed: === Running tests -We recommend tests to be run with a fresh install of all dependencies in a local folder that won't affect your ruby install (a `.bundle/` in this directory): +We recommend tests to be run with a fresh install of all dependencies in a local folder that won't affect your Ruby install (a `.bundle/` in this directory): bundle --path=.bundle/gems --binstubs=.bundle/.bin @@ -383,7 +384,7 @@ However, if you have all dependencies properly installed this command should run === Generating HTML test target -Tests were bootstrapped by https://github.com/asciidoctor/asciidoctor-doctest/#generate-examples[generating them from asciidoctor-doctest's test corpus] and current asciidoctor-revealjs' slim template engine. +Tests were bootstrapped by https://github.com/asciidoctor/asciidoctor-doctest/#generate-examples[generating them from asciidoctor-doctest's test corpus^] and current asciidoctor-revealjs' slim template engine. This is done using the following command: bundle exec rake doctest:generate FORCE=y @@ -396,19 +397,22 @@ Resulting slides are kept in `test/doctest/`. == Netlify Integration -On every commit or PR, the https://www.netlify.com[Netlify] service will convert some examples into slides and host the resulting pages on its platform where it will be visible by anyone. +On every commit or PR, the {url-netlify}[Netlify^] service will convert some examples into slides and host the resulting pages on its platform where it will be visible by anyone. It hosts the converted HTML files, reveal.js framework and static content like images and CSS. -This integration will allow us to easily preview PRs and demo features to users (source and converted result). +This integration will allow us to preview PRs and demo features to users (source and converted result). See the `publish` rake task in `Rakefile` and the `netlify.toml` configuration file. === Sensitive Data Accidentally Pushed Out Only content that is copied into the `public/` directory will be published on the Netlify site. If, by accident, something sensitive is copied over there, delete it, rewrite the git history to remove the sensitive information and force push the branch. -Reach out to our netlify integration contact to make sure that deployed branches were rebuilt and no longer contain the sensitive information. +Reach out to our Netlify integration contact to make sure that deployed branches were rebuilt and no longer contain the sensitive information. === Integration Contact -Main Contact: https://github.com/Mogztter[@Mogztter] +Main Contact: {url-gh-mogztter}[@Mogztter^] -Also, in order to stay with a free plan, only the following people have control over our netlify integration: https://github.com/Mogztter[@Mogztter], https://github.com/mojavelinux[@mojavelinux] and https://github.com/graphitefriction[@graphitefriction]. +Also, in order to stay with a free plan, only the following people have control over our Netlify integration: +{url-gh-mogztter}[@Mogztter^], +{url-gh-mojavelinux}[@mojavelinux^] and +{url-gh-graphitefriction}[@graphitefriction^]. diff --git a/docs/modules/setup/pages/compatibility-matrix.adoc b/docs/modules/setup/pages/compatibility-matrix.adoc index 4224393d..61c1b458 100644 --- a/docs/modules/setup/pages/compatibility-matrix.adoc +++ b/docs/modules/setup/pages/compatibility-matrix.adoc @@ -30,7 +30,7 @@ Due to our Ruby to JavaScript conversion process, published npm packages have st This table tracks this compatibility. |=== -|Asciidoctor-reveal.js version |Asciidoctor.js version +|Asciidoctor reveal.js version |Asciidoctor.js version |3.x |2.x diff --git a/docs/modules/setup/pages/minimum-requirements.adoc b/docs/modules/setup/pages/minimum-requirements.adoc index 29b6a7b5..1402f2e2 100644 --- a/docs/modules/setup/pages/minimum-requirements.adoc +++ b/docs/modules/setup/pages/minimum-requirements.adoc @@ -3,11 +3,11 @@ Our requirements are expressed in our packages and by our dependencies. Basically, all you need is the package manager of the flavor of Asciidoctor reveal.js you are interested to run: -* With Ruby / Bundler: A https://www.ruby-lang.org/en/downloads/[recent Ruby] and https://bundler.io/[Bundler] -* With JavaScript (Node.js) / npm: a https://nodejs.org/en/download/[recent Node.js] environment +* With Ruby / Bundler: A {url-ruby-download}[recent Ruby^] and {url-bundler}[Bundler^] +* With JavaScript (Node.js) / npm: a {url-nodejs-download}[recent Node.js^] environment If you need more details about our dependencies check out Asciidoctor dependencies: -* With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor] 2.0.10 -* With JavaScript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js] 2.0.3 +* With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor^] 2.0.10 +* With JavaScript (Node.js) / npm: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js^] 2.0.3 diff --git a/docs/modules/setup/pages/ruby-setup.adoc b/docs/modules/setup/pages/ruby-setup.adoc index 6bb938f0..9217fa8e 100644 --- a/docs/modules/setup/pages/ruby-setup.adoc +++ b/docs/modules/setup/pages/ruby-setup.adoc @@ -1,11 +1,11 @@ = Ruby Setup :navtitle: Ruby -NOTE: To ensure repeatability, we recommend that you manage your presentation projects using http://bundler.io/[bundler]. +NOTE: To ensure repeatability, we recommend that you manage your presentation projects using {url-bundler}[Bundler^]. == Prerequisites -. Install http://bundler.io/[bundler] (if not already installed) using your system's package manager or with: +. Install {url-bundler}[Bundler^] (if not already installed) using your system's package manager or with: $ gem install bundler @@ -17,7 +17,6 @@ or + $ rvm use system - == Install NOTE: These instructions should be repeated for every presentation project. @@ -36,7 +35,7 @@ source 'https://rubygems.org' gem 'asciidoctor-revealjs' # latest released version ---- + -NOTE: For some reason, when you use the system Ruby on Fedora, you also have to add the json gem to the Gemfile. +NOTE: For some reason, when you use the system Ruby on Fedora, you also have to add the `json` gem to the Gemfile. + . Install the gems into the project @@ -63,7 +62,7 @@ convert AsciiDoc source with $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc -TIP: If you are using https://pages.github.com/[GitHub Pages], plan ahead by keeping your source files on `master` branch and all output files on the `gh-pages` branch. +TIP: If you are using {url-gh-pages}[GitHub Pages^], plan ahead by keeping your source files on `master` branch and all output files on the `gh-pages` branch. == Features unique to the Ruby CLI @@ -84,6 +83,6 @@ The feature is activated with the `--template-dir` or `-T` option: $ bundle exec asciidoctor-revealjs -T templates/ CONTENT_FILE.adoc Any individual template file not provided in the directory specified on the command-line will fall back to the template provided by your version of Asciidoctor reveal.js. -Refer to our https://github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates[templates] for inspiration. +Refer to our {url-project-templates}[templates^] for inspiration. This feature hasn't been ported to the JavaScript CLI (and API) or the standalone executables.