resolves #648 refresh documentation

[sturtison]

Will squash and rebase on main before final. Full notes on issue #648

[sturtison]

It's ready for review and any further changes. #648

[ggrossetie]

That's pretty good thanks! 👍🏻 I left a few comments/nitpicks.

[sturtison]

I added back the usage section and moved next steps to the top. Plus some other changes at the top, with the idea of speed and usefulness fast. This includes a little "mini horizontal menu"

[sturtison]

Ready for review and any further changes.

[sturtison]

Niggles, dictionary lists separated, and last typos fixed after a re-read.

[sturtison]

Ready for review and further changes.

[sturtison]

Applied the same conventions to the local installation section. No further changes from my side. Will note them in the review if I find something. Squashed and rebased on main. Ready for review and further changes.

[sturtison]

Putting :figure-caption!: in the header did not remove the automatic "Figure 1." text above images, at odds to https://docs.asciidoctor.org/asciidoc/latest/macros/images/#figure-caption-label

Using [caption=] instead.

[sturtison]

I'm concerned about the image size. We could minimise the image size to exactly what is needed and no more, and perhaps drop the "inactive" image to save space.

[mojavelinux]

Putting :figure-caption!: in the header did not remove the automatic "Figure 1." text above images, at odds to docs.asciidoctor.org/asciidoc/latest/macros/images/#figure-caption-label

That's because GitHub is using an extremely old version of Asciidoctor (2.0.11), and is thus affected by this resolved issue: https://github.com/asciidoctor/asciidoctor/issues/2586

[mojavelinux]

I'm going to repost here what I wrote in the project chat:

While I love to see the documentation being worked on and improved, I'm not convinced this is the right place for it. We have a documentation site at https://docs.asciidoctor.org/. That's where user-facing documentation for Asciidoctor project should go. We're in the (rather slow) process of striping down the README files in the projects to being minimal introductions so they don't end up becoming monoliths. And GitHub is not a great rendering environment for complete content. That's why we put the investment into making https://docs.asciidoctor.org/.

[sturtison]

That's a good point. I'll read the docs there in more depth to better link to them where needed. I'd prefer to help move things in the right direction.

This branch is draft and there is no imperative to merge.

[sturtison]

https://docs.asciidoctor.org/asciidoctor/latest/tooling/#web-browser-add-ons-preview-only

Would the above be a good place to start?

To strip down the extension readme would be to provide the minimum to get it installed, with links to content in docs.asciidoctor.org to cover more detailed aspects.

I think that if we were to continue with the readme draft as it is, we would be creating a distributed monolith which s definitely not in your goals.

Mods to the readme and the official docs can be done in tandem to make them consistent.

[mojavelinux]

Would the above be a good place to start?

I think this extension deserves it's own top-level project in the docs (taken from this repository). It's not something that should be fused with the Asciidoctor core documentation. In other words, it will appear in the list on the left hand side of this page: https://docs.asciidoctor.org/

And we also don't want all the info on the same page. Each page should be dedicated to some aspect so that the information is easy to consume and easy to search.

To strip down the extension readme would be to provide the minimum to get it installed, with links to content in docs.asciidoctor.org to cover more detailed aspects.

Correct. The README should be stingy. It should be welcoming enough to give an impression, but not delve into details.

I think that if we were to continue with the readme draft as it is, we would be creating a distributed monolith which s definitely not in your goals.

Exactly. Our experience is that long READMEs are very hard to maintain and get out of date quickly. Pages in the documentation site receive lots of attention, they are searchable, and they welcome people to edit them (using the Edit this Page link).

Mods to the readme and the official docs can be done in tandem to make them consistent.

Ideally, the README should be so simple that it almost never has to be updated. But even if it does, it would be part of the same PR that updates the docs.

[sturtison]

I'll able to help do this over time. Not sure how or where to approach this with the asciidoctor project, so this is what I would put forward as a tentative first guide to the docs and associated docs instead of just focusing on the readme.

For sure this is not new and you've already put effort and sweat into this, so instead of me commenting from the side here is a tentative TOC, perhaps with too much, with all errors and mistakes mine.

Text in "quotes" - "What the reader is thinking" Text in (round brackets) - (Guide to the writer, editors notes)

Happy to help move your ideas for the docs forward in any way I can.

• Goals Asciidoctor Browser Extension as a top level Antora component in docs.asciidoctor.org No change to the README.adoc over time, and when necessary, update it and the docs as the same time. No overlap between the docs and the README.adoc, CONTRIBUTING.adoc, RELEASE.adoc, BUILD.adoc Sufficient for the relevant audience performing the task

• Guidelines Write sparsely without verbosity, nothing extra. In all sections, DRY and link back to other docs.asciidoctor.org as needed.

Asciidoctor Browser Extension pages and topics (Some subtopics may roll up into the parent adoc page)

• Getting Started

• Features

• What's new - (Not much change, is this really necessary? Place holder for when they do.)

• Install guide How to install from a webstore How to install locally - for developers, organizations, air gaps When What's needed

• View your first AsciiDoc - "Open and view an asciidoc that we provide to you" (An activity for the person to do. Perhaps they proceed to use cases after.) Setup The file Open the file Toggle inactive, active

• Tour - "As a new plugin user, what's most important to know" (No customization other then what can be selected from the options) Tour Overview Tour Setup ** Tour

• Tutorials Use in combination with a text editor - "use the extension to show an AsciiDoc file, save and see the updates" Adding a new stylesheet (link out?) Creating a new stylesheet (link out?) Tweaking the CSS (link out?)

• Extension Options - "What options are available" (Answers the question, but not in-depth - link to the other pages for that) Custom attributes Safe mode Files extension Poll for changes Diagrams extension ** Enable Kroki server URL Theme/stylesheet Add a stylesheet ** Load the javascript

(Extension options in detail)

• Safe mode - "Will it be safe for me? What are the risks of selecting unsafe?" (discussion on safe modes)

• Where can the plugin be used "Where can I use it and what should I configure to do so?" Local files Raw hosted git files GitHub GitLab *** BitBucket

• Productivity use cases Writing minimal notes ** Minimal Custom attributes to set (these custom attributes save you typing them into all your notes) What they affect Launch a browser while editing * From pure text editors ** Notepad++ *** VIM From IDEs "Why would I do this when I have an IDE plugin?" (While many IDEs have a plugin, sometimes its good to just view the raw AsciiDoc without other helpers) IntelliJ/PyCharm External Tools VSCODE **** Atom

• Extend and customize - "I want to change how it looks and feels, be more accessible, standardise" (What do people want to do) Overview (what you can do, the limits, and when you should consider alternatives such as Asciidoctor.js etc) Change the appearance of the HTML Change the appearance of printed PDFs Select different stylesheets Stylesheet sources Add a stylesheet Define the stylesheet Where to host the stylesheet Adding your own CSS Use an organization standard stylesheet

• Troubleshooting / FAQ Active but not viewing the HTML - "It it a URL file://...? Check allow File URLs is enabled" Can't see the extension icon - "Configure your browser to show/pin the extension icon"

• Privacy policy Does it track? What information leaves the browser?

• Known issues

• Release and update policy

README.adoc

• Summary (links to full docs on docs.asciidoctor.org)
• Webstore links
• Usage (general)
• Install "As an existing or potential first time user, I just want to get it installed correctly" Firefox Chromium (Chrome, Brave, Edge, Opera) - (Also to set the enable allow file:// URLs)
• Options (No full list or description, but a link to docs.asciidoctor.org)
• Known issues

Change README.adoc when:

• Links to the extension in webstores change
• New webstore
• New browser
• Known issues fixed or found

CONTRIBUTING.adoc "As a writer, coder, distributor, how do I contribute to the project"

BUILD.adoc "As a developer or distributor, how do I build the project?"

RELEASING.adoc "As a project maintainer, how do I do the final build and release the project?"

[ggrossetie]

The first step would be to create an Antora documentation component. If you are not familiar with Antora directory structure I can bootstrap it for you.

[sturtison]

Thank @ggrossetie I wasn't sure if I should start the Antora component or not. It has some starting values based on looking at the other top level components. The component name is just a first guess also. The nav.adoc so far has the outline of the docs and I'll work though that gradually.

[ggrossetie]

@sturtison Live preview: https://deploy-preview-75--asciidoctor-docs.netlify.app/browser-extension/latest/

[sturtison]

@sturtison Live preview: https://deploy-preview-75--asciidoctor-docs.netlify.app/browser-extension/latest/

That looks great!

[sturtison]

That's all the updates from me for today. Thank you for the reviews.

[sturtison]

Will squash and rebase.

[sturtison]

Putting details here. Will make commit message short.

Refresh documentation

• Add feature tolerates markdown; Improve try-it-yourself
• Add content for options. Known issues is the Firefox issues page.
• Add, update, arrange and simplify docs
• Add edit step to try it yourself; add javascript to options
• Use Chromium-based not Chromium; options.adoc table
• custom-attributes.adoc: simplify language
• Update features with intro, features and simplification
• Use Web Store not web-store or webstore
• Remove reminder note; simplifications
• Remove super easy, simply and like terms
• Update install.adoc: Accept readability changes
• Co-authored-by: Guillaume Grossetie ggrossetie@yuzutech.fr
• Update install.adoc: Accept grammar changes
• Co-authored-by: Guillaume Grossetie ggrossetie@yuzutech.fr
• Update index.adoc: Use term Chromium-based
• Co-authored-by: Guillaume Grossetie ggrossetie@yuzutech.fr
• Update index.adoc navtitle
• Co-authored-by: Guillaume Grossetie ggrossetie@yuzutech.fr
• Fix diagrams-extension-sequence
• Add and update antora pages and README.adoc
• README.adoc is sparser and uses the same "Install" terminology
• Antora documentation
• Initial commit of Antora component
• be inside the mind of a foundations learner of:
  • AsciiDoc
  • Installing browser extensions
• reorder sections
  • Essential material to the top
  • Advanced material to the end
• use [caption=] instead of :figure-caption!:
• remove http image of asciidoctor logo
• use minimal indent with preformatted text
• remove .Note above NOTE:
• use xref and target document name for the inter-document reference
• use image:: not image: when they have a title
• add new to asciidoc section
• add example active and inactive png files
• add mini-menu
• add alt-text to images
• use URI attributes for most URLs
• add sections
• expand option descriptions
• advise read of data leaving the computer with Kroki.io
• remove closing steps that aren't steps and convert them to closing step list comments.
• replace some admonitions with focused text
• chromium-browser-list attribute for consistency
• refresh learn more URLs with docs.asciidoctor.org links
• add known issues section for the Firefox bugs and update their last updated status
• more detailed guide to open the Chrome extensions dialog
• use same conventions for local installation
• remove repeated empty lines
• use positional attributes for image height & width
• use compact cols=4*a instead of cols="a,a,a,a"
• ensure blank line after every section title
• ensure blank line before every block start

[sturtison]

Ready for reviews, further comment or changes. #648

[sturtison]

Wow. So many features, that it may be better use a topic folders option and feature to give clarity and split up the the page more.

[sturtison]

Will squash and rebase - after reviews and other changes.

[ggrossetie]

Netlify build is failing: https://app.netlify.com/sites/asciidoctor-docs/deploys/648a31b534a1a4088dabe1f8

11:34:41 PM:   ✖ FAIL load https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-MML-AM_HTMLorMML
11:34:41 PM:   | operator: load
11:34:41 PM:   | expected: 200 https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-MML-AM_HTMLorMML
11:34:41 PM:   |   actual: socket hang up
11:34:41 PM:   |       at: public/asciidoc/latest/stem/index.html:1607:20 <script async="" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-MML-AM_HTMLorMML">...</script>
11:34:41 PM:   ✖ FAIL fragment-check public/browser-extension/latest/features/index.html --> #asciidoc::asciidoc-vs-markdown
11:34:41 PM:   | operator: fragment-check
11:34:41 PM:   | expected: id="asciidoc::asciidoc-vs-markdown"
11:34:41 PM:   |       at: public/browser-extension/latest/features/index.html:460:24 <a href="#asciidoc::asciidoc-vs-markdown">...</a>
11:34:41 PM:   ✖ FAIL fragment-check public/browser-extension/latest/features/index.html --> #asciidoctor:migrate:markdown
11:34:41 PM:   | operator: fragment-check
11:34:41 PM:   | expected: id="asciidoctor:migrate:markdown"
11:34:41 PM:   |       at: public/browser-extension/latest/features/index.html:463:27 <a href="#asciidoctor:migrate:markdown">...</a>
11:34:41 PM:   ✖ FAIL fragment-check public/browser-extension/latest/features/index.html --> ../options/#poll-for-changes
11:34:41 PM:   | operator: fragment-check
11:34:41 PM:   | expected: id="poll-for-changes"
11:34:41 PM:   |       at: public/browser-extension/latest/features/index.html:353:17 <a href="../options/#poll-for-changes" class="xref page">...</a>
11:34:41 PM:   ✖ FAIL fragment-check public/browser-extension/latest/features/index.html --> ../options/#theme-stylesheet
11:34:41 PM:   | operator: fragment-check
11:34:41 PM:   | expected: id="theme-stylesheet"
11:34:41 PM:   |       at: public/browser-extension/latest/features/index.html:548:24 <a href="../options/#theme-stylesheet" class="xref page">...</a>

[mojavelinux]

FYI, there are a few broken links in these docs. Nothing urgent, just wanted you to be aware of it. https://app.netlify.com/sites/asciidoctor-docs/deploys/648da4783b64507ca6ec6afc

[sturtison]

Rebased on main to get latest changes before force pushing to this branch.

[sturtison]

I thought there was a problem, but it was because I'd appended the query parameters to the URL, instead of making sure they were between the document and any (#) fragment. Updated the docs to be more specific.

[mojavelinux]

Yep, once the fragment starts, everything after that is fragment. It always has to be the last thing in the URL.

[sturtison]

There's some duplication of use cases at the moment that I'm still moving. I think that the options should describe how to update the options. Use cases overall belong in the features.adoc, because to exercise a use case, you could use one or more options or ways to do things.

[mojavelinux]

I think a screenshot of the extension in action should be shown on the start page. Otherwise, that page looks quite barren and doesn't entice a reader to dig deeper. wdyt?

[sturtison]

Yes, I think an animated gif of a few of the use cases would be good. I have some ideas..... A "lorem" demo page would also help to show some of the use cases. So a "I saw it" "I can do it" visual.

[sturtison]

What is your opinion or view on what to call the "Asciidoctor Browser Extension" in colloquial terms?

• ... the extension; the Extension; the Asciidoctor Browser Extension
• ... the plugin
• ... the viewer; the Viewer; the AsciiDoc Viewer
• ... the previewer

I'm tending towards the simplest - "viewer". It's short and does what it says. It may be a preview in a technical sense if you are working with publishing tool chain, however "viewer" says exactly what it does, views the AsciiDoc file straight to your Browser as HTML.

At work, we typically use the proper names each time for (C) reasons.

[ggrossetie]

A "lorem" demo page would also help to show some of the use cases.

I would prefer to use a real use case. I believe that two popular use cases are:

• Get a better preview of AsciiDoc documents from GitHub or GitLab. I think we could use: https://gitlab.com/antora/antora/-/raw/main/README.adoc?source-highlighter=highlight.js

We could also use an AsciiDoc page from Fedora (https://gitlab.com/fedora/docs/community-tools/documentation-contributors-guide/-/raw/main/modules/ROOT/pages/organizational/charter.adoc) and showcase how to use a custom theme (we could use the Fedora skin from https://darshandsoni.com/asciidoctor-skins/)

• Get a preview of a local AsciiDoc file (i.e., you don't need to have an IDE, you can edit the AsciiDoc file using any text editor). Might be a good idea to use Windows with Notepad. Or the same content on different text editors / different OS with the same preview on the right. Should give a sense of you can preview AsciiDoc file "everywhere" and use any text editor. We might even use different browsers as well.

[sturtison]

TBH I like those documents you mentioned, as I find the Asciidoctor and Antora communities to be examplar.

[ggrossetie]

I will try to work on something since I have a Windows, macOS and Linux at hand 😍

[ggrossetie]

I've created a Figma design to produce every combinations. Here's a sneak peek:

I'm using https://github.com/mraible/angular-book to showcase the browser extension. @mraible let me know if that's OK.

[ggrossetie]

https://github.com/asciidoctor/asciidoctor-browser-extension/assets/333276/da529169-6348-4ed8-9708-a1452fabdf29

[sturtison]

That's very nice and eye-catching for the front page! Are you thinking to convert it to an animated gif to save space?

[sturtison]

One idea, given the use of the angular page, would be to view it with a TOC, adding ?toc=left to the URL.

[ggrossetie]

It would be cool if the user could select an OS, a browser and a text editor and see the result. We could even detect the current OS/browser and show the corresponding result.

Anyway, as a first step, I think a gif/webp is enough.

[ggrossetie]

Actually a gif is bigger:

However, I was able to generate a 1,1 Mo webp animated image. We might want to use a static image and load the animated image in the background then switch the static image with the animated image.

[ggrossetie]

And we are live https://docs.asciidoctor.org/browser-extension/latest/ 🎉 🎉 🎉

Many thanks @sturtison for your work 🤗

[sturtison]

Awesome! Thanks for your patience, help and guidance 👍