An extension that provides live preview, syntax highlighting and snippets for the AsciiDoc format using Asciidoctor flavor.

Contents

• Adoc的初步接触介绍markdown 大家基本都熟悉，作为程序员，进行知识管理，用markdown 有点很多。例如我就喜欢他语法简洁，在积累下来的大量文档中搜索变的比较容易。比word要强多了。我的这篇博客就是用markdown所写。adoc是markdown更好一些的写文档工具，比markdown有更为丰富的功能。.
• Md, markdown, goldmark: Note that you can set the default handler of md and markdown to something else, see Configure Markup. New in v0.60.0: Blackfriday: blackfriday: Blackfriday will eventually be deprecated. MMark: mmark: Mmark is deprecated and will be removed in a future release. Emacs Org-Mode: org: See go-org. AsciiDoc: asciidocext, adoc, ad.

• AsciiDoc support for Visual Studio Code
  • How to Use
  • Build and Install from Source

Convert a Single Markdown File to AsciiDoc. Given that I only need three options, here’s an example of the command that I’d run to convert a Markdown file to AsciiDoc (formatted for readability): kramdoc -format=GFM -output=getting-started.adoc -wrap=ventilate getting-started.md. Md, markdown, goldmark: Note that you can set the default handler of md and markdown to something else, see Configure Markup. New in v0.60.0: Blackfriday: blackfriday: Blackfriday will eventually be deprecated. MMark: mmark: Mmark is deprecated and will be removed in a future release. Emacs Org-Mode: org: See go-org. AsciiDoc: asciidocext, adoc, ad.

How to Install

Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter:

ext install asciidoctor.asciidoctor-vscode

Alternatively you can use the built-in extension browser to find the AsciiDoc by joaompinto extension and install it.

How to Use

The extension activates automatically when opening an AsciiDoc file (.adoc, .ad, .asc, .asciidoc).

Preview

To show the preview you can use the same commands as the Markdown extension:

• Toggle Preview - ctrl+shift+v (Mac: cmd+shift+v)
• Open Preview to the Side - ctrl+k v (Mac: cmd+k v)

The preview refreshes automatically, but it can also be forced with the AsciiDoc: Refresh Preview command.

The preview supports setting attributes through the asciidoc.preview.attributes option.

By default the preview style follows the VSCode theme (workbench.colorTheme). To use Asciidoctor's style set option asciidoc.preview.useEditorStyle to false. It is also possible to set your own preview stylesheet with the asciidoc.preview.style option.

(See more details under Options)

Export as PDF

The extension provides a quick command to export your AsciiDoc file as PDF.

• Open the command palette - ctrl+shift+p or F1 (Mac: cmd+shift+p)
• Select AsciiDoc: Export document as PDF
• Choose the folder and filename for the generated PDF

By default a separate binary is downloaded and used to render the document in PDF format. To use Asciidoctor PDF set option asciidoc.use_asciidoctorpdf to true.
(See more details under Options)

Save as HTML

The extension provides a quick command to export your AsciiDoc file as HTML using the default Asciidoctor stylesheet.

• Open the command palette - ctrl+shift+p or F1 (Mac: cmd+shift+p)
• Select AsciiDoc: Save HTML document
• The file is generated in the same folder as the source document

The shortcout key of ctrl+alt+s (Mac: cmd+alt+s) will also save the document.

Save to Docbook

The extension provides a quick command to export your AsciiDoc file as Docbook.

• Open the command palette - ctrl+shift+p or F1 (Mac: cmd+shift+p)
• Select AsciiDoc: Save to Docbook
• The file is generated in the same folder as the source document

Docbook 5 is supported out of the box.

Docbook 4.5 is more difficut to support (mostly because it's ancient).

Docbook 4.5 requires the use of command line Asciidoctor and requires the use of either the community maintained docbook converter (which can be installed using specific_install) or an older version of Asciidoctor (v1.5.8 or earlier).

To use Docbook 4.5, the following is known to work on Debian based systems:

1. From the command line, install the specific_install gem: gem install specific_install
2. Then install the community supported Docbook 4.5 converter from the command line: gem specific_install -l https://github.com/asciidoctor/asciidoctor-docbook45
3. Then change the User setting asciidoc.asciidoctor_command to: asciidoctor -r asciidoctor-docbook45
4. Finally, untick (disable) asciidoc.use_asciidoctor_js

Snippets

Several code snippets are provided including but not limited to: include statements, images, links, header, headings, lists, blocks, etc...

For a full list open the command palette and select Insert Snippet.

Adoc Vs Markdown

User Settings

This extension is controlled by a multitude of user settings.

The following list contains all the options and their default value.

Identifying the VS Code Environment

The env-vscode attribute is set on all output documents. If you need to identify or handle the VS Code environment you can use an ifdef expression similar to the following:

Diagram Integration

This extension supports a wide range of diagrams from BPMN to Graphviz to PlantUML and Vega graphs using kroki and asciidoctor-kroki.

You can see the full range on the kroki website.

Note that this extension will send graph information to https://kroki.io. If this is an issue it is also possible to use your own kroki instance (see the instructions for further information).

To enable diagram support, set the use_kroki parameter in your User Settings to true.

To cache and save diagrams locally set the kroki-fetch-diagram attribute in your document header:

This will store images by default in your document folder, however you may also set imagesdir to store them elsewhere:

Build and Install from Source

Manual

Script

The script included in the repository automates all operations needed to build the extension. Run bash ./script/build.sh help for more information.

WARNING: The script only works in MacOS and Windows

Issues

If you encounter any problems with the extension and cannot find the solution yourself, please open an issue in the dedicated GitHub page: asciidoctor-vscode/issues.

Before opening an issue, please make sure that it is not a duplicate. Your problem may have already been brought up by another user and been solved: asciidoctor-vscode/issues all.

When you do open an issue, remember to include the following information:

1. Description of the issue
2. VSCode version, OS (Help -> About) and extension version
3. Steps to reproduce the issue
   IMPORTANT: We cannot solve the issue if you do not explain how you encountered it
4. If the problem occurs only with a specific file, attach it, together with any screnshot that might better show what the issue is.

If your issue only appeared after updating to a new version of the extension, you can roll back to a previous one via the extensions browser. Click on the small gear icon beside the AsciiDoc extension, then select Install Another Version.... A selection menu will appear allowing you to select which version you want to install.

Contributing

To contribute simply clone the repository and then commit your changes. When you do a pull requests please clearly highlight what you changed in the pull comment.

Do not update the extension version or changelog, it will be done by the maintainers when a new version is released.

If you want to update the readme, you are free to fix typos, errors, add or improve descriptions, but if you have a style change in mind please use an issue (or specific pull request) so that it can be discussed.

Credits

Adoc Markdown Schedule

• AsciiDoc by Stuart Rackham
• Asciidoctor organization for the the language flavor
• Asciidoctor.js for the preview
• Asciidoctor PDF for the Export to PDF function
• wkhtmltopdf for the Export to PDF function

All the following people who have contributed to the extension:

Adoc Markdown Table

• Achille Lacoin
• Andre Bossert
• Bart Sokol
• chriskoerner
• cirrusj
• Dan Allen
• Daniel Mulholland
• danyill
• Garrett D'Amore
• Gigacee
• Guillaume Grossetie
• Jackson C. Wiebe
• jacksoncougar
• João Pinto
• Johannes Rössel
• Joshua Stafman
• Kevin Palmowski
• Lars Hvam
• larshp
• Loïc PÉRON
• Marcelo Alvim
• Mark Roszko
• Masanori Asano
• Matteo Campinoti
• MatteoCampinoti94
• ojn
• Øyvind Hansen
• sgn
• shaneknysh
• Stephen Pegoraro
• Tatsunori Uchino
• Tilmann Oestreich
• Waldir Pimenta