Refresh README.adoc and associated docs

[sturtison]

Could I help you with your plugin by suggesting some changes via a draft PR to refresh the docs?

See draft PR https://github.com/asciidoctor/asciidoctor-browser-extension/pull/649

See latest draft page here: https://github.com/sturtison/asciidoctor-browser-extension/blob/docs/issue-648-refresh-docs-draft/README.adoc

• Streamline for a person who is a foundational user of AsciiDoc and installing browser extensions
• Reorder sections (essential towards the top, advance towards the end)
• Rename the hacking.adoc to CONTRIBUTING.adoc in line with convention and the README.adoc
• Footnote the Firefox bugs and add their last updated date.

Proposed TOC for the Asciidoctor Browser Extension

• Get started
  • Install from the browser extension webstores
  • Install in Chrome, Chromium, Brave or Opera
  • Install in Firefox
• Configuring extension options
  • Chrome, Chromium, Brave or Opera
  • Firefox
  • Common options
• Local installations
  • Chrome, Chromium, Brave or Opera
  • Firefox
• Contributing
• Changelog
• Copyright

Thank you for a great plugin.

Edits: Add link to the draft PR https://github.com/asciidoctor/asciidoctor-browser-extension/pull/649, to the latest page

[ggrossetie]

That's sounds great 👍🏻

[sturtison]

This does not provide a walk through like https://github.com/asciidoctor/asciidoctor-browser-extension/issues/528 however it does lead the different reader groups through the install in more detail.

Some adoption road bumps have been:

• The browser choice (Chromium or FireFox)
• Confusion between the Browser's settings for the extension, and the Extension Settings.
• Enterprise users having to have the plugin distributed internally by IT support before use.

[sturtison]

Squashed and rebased on main.

• add asciidoctor icon to introduction
• add mini-menu
• add alt-text to webstore images
• use URI attributes for most URLs
• 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
• 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

[sturtison]

• Example Two images: active, inactive
• New to AsciiDoc Tiny introduction to AsciiDoc and link to asciidoc.org etc Example from this page The previous section in AsciiDoc - Shows use of attributes etc. Try it yourself How to reproduce the images shown in Examples.

[sturtison]

The URIs for the images will have to be changed if the PR is accepted as they refer to the raw.githubusercontent on the forked branch.

[sturtison]

Looking for the recommended way to show the my.email@example.com in the as-is block.

https://github.com/sturtison/asciidoctor-browser-extension/blob/5f0dd5273a75b0e38b13ac680ac4cfa830a7c5b0/README.adoc#L218-L224

[sturtison]

Looking for the recommended way to show the my.email@example.com in the as-is block.

https://github.com/sturtison/asciidoctor-browser-extension/blob/5f0dd5273a75b0e38b13ac680ac4cfa830a7c5b0/README.adoc#L218-L224

Fixed.

[sturtison]

The URIs for the images will have to be changed if the PR is accepted as they refer to the raw.githubusercontent on the forked branch.

Fixed by @ggrossetie to be:url-asciidoctor-sc-image: https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor/screenshot.png in features.adoc

[mojavelinux]

Truly excellent work @sturtison and @ggrossetie!

[mojavelinux]

To ensure that docs changes get published right away (instead of nightly), you may be interested in setting up the deploy-docs workflow. See https://github.com/asciidoctor/asciidoctor-pdf/blob/v2.3.x/.github/workflows/deploy-docs.yml for an example. I've already set up the secret for that workflow to use.