add hosted git repositories to tooling page

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/modules/tooling/pages/index.adoc b/docs/modules/tooling/pages/index.adoc
index 4ffecd21..ef139ad5 100644
--- a/docs/modules/tooling/pages/index.adoc
+++ b/docs/modules/tooling/pages/index.adoc
@@ -16,6 +16,31 @@ In fact, you shouldn't use these programs because they add cruft to your documen
 
 Here's an overview of the different ways to preview and edit your AsciiDoc documents.
 
+== 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.
+
+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.
+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.
+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.
+
+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.
+
 == Web browser add-ons (preview only)
 
 To preview an AsciiDoc document in a web browser, install the {url-chrome-extension}[Chrome extension^], the {url-edge-addon}[Edge add-on^], the {url-firefox-addon}[Firefox add-on^], or the {url-opera-extension}[Opera extension^] (all produced from the same code base).