Skip to content

Commit

Permalink
Edit docs about AsciiDoc preview in hosted git repositories (PR #4583)
Browse files Browse the repository at this point in the history
  • Loading branch information
jepotter1 authored and mojavelinux committed May 16, 2024
1 parent 9c21d85 commit abafda1
Showing 1 changed file with 13 additions and 14 deletions.
27 changes: 13 additions & 14 deletions docs/modules/tooling/pages/index.adoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
= AsciiDoc Tooling
:experimental:
:url-chrome-extension: https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia
:url-edge-addon: https://microsoftedge.microsoft.com/addons/detail/asciidoctorjs-live-previ/pefkelkanablhjdekgdahplkccnbdggd
:url-firefox-addon: https://addons.mozilla.org/en/firefox/addon/asciidoctorjs-live-preview
Expand All @@ -19,28 +20,26 @@ Here's an overview of the different ways to preview and edit your AsciiDoc docum

== Hosted git repositories

The two most popular git repository hosts, GitHub and GitLab, support editing and previewing AsciiDoc files.
In order to activate this support, the file must have a supported AsciiDoc extension, such as .adoc.
Many popular git repository hosts, including https://github.com/[GitHub], https://about.gitlab.com/[GitLab], and https://codeberg.org/[Codeberg], support editing and previewing AsciiDoc files.
In order to activate this support, the file must have a supported AsciiDoc extension, such as `.adoc`.

When you browse to an AsciiDoc file in the repository view, you will see an HTML preview of the AsciiDoc content.
That preview is powered by Asciidoctor.
When you view an AsciiDoc file on these sites, you will see an HTML preview of the AsciiDoc content.
This preview is powered by Asciidoctor.
The HTML that's rendered is the embedded output produced by the built-in HTML converter.
That means it won't look like a standalone HTML document generated by Asciidoctor.
This means it won't look like a standalone HTML document generated by Asciidoctor.
Rather, the HTML is styled to match the theme of the hosting service and sanitized, so it does not impact the rendering of the page.
That means that certain features may not be available.
This means that certain features may not be available.

GitHub and GitLab apply syntax highlighting to source blocks.
Both services also add floating anchor links next to section titles.
You can deep link to a specific section or to another anchor by adding a fragment identifier to the URL.

Both services apply syntax highlighting to source blocks.
Both services also add a floating anchor link next to section titles.
You can deep link to a specific section or other anchor by adding a fragment identifier to the URL.
The AsciiDoc preview on GitLab currently supports more AsciiDoc features than on GitHub.
On GitLab, you can find support for include directives, admonition icons, diagrams, and STEM expressions.
GitHub, on the other hand, provides a table of contents browser, whereas on GitLab you must add a TOC explicitly using the `toc` attribute.

On GitHub, if you want to see the source of the AsciiDoc file instead of the preview, append `?plain=1` to the end of the URL.

If you click the Edit button, you will see the syntax highlighted source of the AsciiDoc file.
In edit mode, you can view a preview of the modified source before you commit the changes.
GitLab allows you to edit multiple files at once using its Web IDE.
On GitHub, if you want to see the source of an AsciiDoc file instead of the preview, click the btn:[Code] button or append `?plain=1` to the end of the URL.
Alternatively, if you enter edit mode by clicking the btn:[Edit file] button, you can modify the source of the AsciiDoc file and see a preview of the modified source before you commit your changes.

== Web browser add-ons (preview only)

Expand Down

0 comments on commit abafda1

Please sign in to comment.