From 451c61f86eb10afd87aa47f844d80b8c80b32e03 Mon Sep 17 00:00:00 2001 From: Victor Toni Date: Mon, 11 Mar 2024 14:12:21 +0100 Subject: [PATCH 1/3] Rename README / CHANGELOG before conversion to keep history --- CHANGELOG.md => CHANGELOG.adoc | 0 README.md => README.adoc | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename CHANGELOG.md => CHANGELOG.adoc (100%) rename README.md => README.adoc (100%) diff --git a/CHANGELOG.md b/CHANGELOG.adoc similarity index 100% rename from CHANGELOG.md rename to CHANGELOG.adoc diff --git a/README.md b/README.adoc similarity index 100% rename from README.md rename to README.adoc From a59d3ce9bbf673496ae53b55d4bf85bb37aa7eae Mon Sep 17 00:00:00 2001 From: Victor Toni Date: Mon, 11 Mar 2024 14:13:57 +0100 Subject: [PATCH 2/3] Conversion of README / CHANGELOG from Markdown to AsciiDoc using kramdown --- CHANGELOG.adoc | 605 ++++++++++++++++++++++++------------------------- README.adoc | 351 ++++++++++++++++++---------- 2 files changed, 526 insertions(+), 430 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 9949d2b5..c4814f7b 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,385 +1,372 @@ -# CHANGELOG += CHANGELOG -## Unreleased +== Unreleased -### Bug fixes +=== Bug fixes * Fix a regression on xref introduced in 3.2.1 by @ViToni -### Infrastructure +=== Infrastructure * Bump dependencies by @ViToni -## 3.2.1 (2024-03-20) +== 3.2.1 (2024-03-20) -### Improvements +=== Improvements * Use color variable defined by theme for ToC by @ViToni in #850 -### Bug fixes +=== Bug fixes * Fix non working xref in preview pane by @ViToni in #853 -## 3.1.12 (2024-02-11) +== 3.1.12 (2024-02-11) -### Bug fixes +=== Bug fixes -- Only prompt to enable Antora when antora.yml is not empty (#847) -- Consistent code completion for includes (#839) -- Fix highlighting a footnote with id (#835) +* Only prompt to enable Antora when antora.yml is not empty (#847) +* Consistent code completion for includes (#839) +* Fix highlighting a footnote with id (#835) -### Improvements +=== Improvements -- Add doc role when the asciidoc page is used in an antora context (#845) -- Bump dependencies (#840) -- If Antora popup is closed (no answer) ask again later (#841) -- Improve autolink feature (#836) +* Add doc role when the asciidoc page is used in an antora context (#845) +* Bump dependencies (#840) +* If Antora popup is closed (no answer) ask again later (#841) +* Improve autolink feature (#836) +== 3.1.10 (2023-11-25) -## 3.1.10 (2023-11-25) +=== Bug fixes -### Bug fixes +* Fix glob pattern while building the Antora content catalog - previously, if the documentation component was located at the root of the workspace the content catalog was empty +* Add `asciidoc.preview.style` directory as a local resource roots in the WebView - hopefully loading stylesheets from outside the workspace will work again! -- Fix glob pattern while building the Antora content catalog - previously, if the documentation component was located at the root of the workspace the content catalog was empty -- Add `asciidoc.preview.style` directory as a local resource roots in the WebView - hopefully loading stylesheets from outside the workspace will work again! +== 3.1.9 (2023-11-19) +=== Bug fixes -## 3.1.9 (2023-11-19) +* Fix drive letter normalization - previously, we were applying `toLowerCase` on the whole path causing the WebView to return 401 on resources such as images (#825) -### Bug fixes +== 3.1.8 (2023-11-12) -- Fix drive letter normalization - previously, we were applying `toLowerCase` on the whole path causing the WebView to return 401 on resources such as images (#825) +=== Bug fixes +* Allow Kroki server in strict CSP defined as a preview attribute +* Add `https` to `style-src` and `script-src` in strict CSP +* Fix a typo on the message "Do you want to active Antora support?" \-> "Do you want to activate Antora support?" -## 3.1.8 (2023-11-12) +=== Improvements -### Bug fixes +* Use a more restrictive glob search for `antora.yml` files +* Use a faster implementation when suggesting to the user to activate Antora support -- Allow Kroki server in strict CSP defined as a preview attribute -- Add `https` to `style-src` and `script-src` in strict CSP -- Fix a typo on the message "Do you want to active Antora support?" -> "Do you want to activate Antora support?" +=== Infrastructure -### Improvements +* Update GitHub Actions to v4 (major) -- Use a more restrictive glob search for `antora.yml` files -- Use a faster implementation when suggesting to the user to activate Antora support +=== Documentation -### Infrastructure +* Mention that `:kroki-fetch-diagram` is unsupported -- Update GitHub Actions to v4 (major) +== 3.1.7 (2023-11-02) -### Documentation +=== Performance -- Mention that `:kroki-fetch-diagram` is unsupported +* Replace `findFiles` by a recursive method that relies on `workspace.fs.stat` in the .asciidoctorconfig feature - should improve performance on large projects (#809) +== 3.1.6 (2023-10-24) -## 3.1.7 (2023-11-02) +=== Bug fixes -### Performance +* Fix preview in the Web version (on vscode.dev) +* Decode section titles in outline (#795) -- Replace `findFiles` by a recursive method that relies on `workspace.fs.stat` in the .asciidoctorconfig feature - should improve performance on large projects (#809) +=== Improvements +* Allow Kroki server in strict CSP +* Added German translation strings - thanks @r0ckarong +* Support Antora resource IDs on include -## 3.1.6 (2023-10-24) +=== Infrastructure -### Bug fixes +* Run CI on Windows (#796) +* Bump dependencies -- Fix preview in the Web version (on vscode.dev) -- Decode section titles in outline (#795) +== 3.1.5 (2023-09-17) -### Improvements +=== Improvements -- Allow Kroki server in strict CSP -- Added German translation strings - thanks @r0ckarong -- Support Antora resource IDs on include +* Update asciidoctor Kroki to 0.17.0 - thanks @sixtysecrun -### Infrastructure +== 3.1.4 (2023-08-29) -- Run CI on Windows (#796) -- Bump dependencies +=== Bug fixes +* Fix the web bundle - the extension was no longer working on vscode.dev (#774) +* Fix the convert and export functions to DocBook - the extension was exporting HTML instead of XML/DocBook (#775) -## 3.1.5 (2023-09-17) +=== Improvements -### Improvements +* Allow MathJax to load in strict CSP (#780) -- Update asciidoctor Kroki to 0.17.0 - thanks @sixtysecrun +=== Documentation +* Update the bug template on GitHub to refer to extension logs (#782) - thanks @jonathan-s -## 3.1.4 (2023-08-29) +== 3.1.3 (2023-07-21) -### Bug fixes +=== Bug fixes -- Fix the web bundle - the extension was no longer working on vscode.dev (#774) -- Fix the convert and export functions to DocBook - the extension was exporting HTML instead of XML/DocBook (#775) +* Ignore Antora documentation component symlinks (#755) +* Disable data-uri in preview (not supported) (#756) +* Provide image completion relative to the `imagesdir` attribute (#759) +* Move `getContent` call after generating the document header (#762) +* Remove the `imagesdir` attribute from image paths when drag and dropping images in the editor (#761) -### Improvements +== 3.1.2 (2023-07-15) -- Allow MathJax to load in strict CSP (#780) +=== Bug fixes -### Documentation +* Use `textDocument.lineAt` to avoid issues with line separators discrepancy (#750) +* Include .asciidoctorconfig, AsciiDoc attributes defined in the extension configuration and Antora AsciiDoc attributes in attributes completion (#754) -- Update the bug template on GitHub to refer to extension logs (#782) - thanks @jonathan-s - - -## 3.1.3 (2023-07-21) - -### Bug fixes - -- Ignore Antora documentation component symlinks (#755) -- Disable data-uri in preview (not supported) (#756) -- Provide image completion relative to the `imagesdir` attribute (#759) -- Move `getContent` call after generating the document header (#762) -- Remove the `imagesdir` attribute from image paths when drag and dropping images in the editor (#761) - - -## 3.1.2 (2023-07-15) - -### Bug fixes - -- Use `textDocument.lineAt` to avoid issues with line separators discrepancy (#750) -- Include .asciidoctorconfig, AsciiDoc attributes defined in the extension configuration and Antora AsciiDoc attributes in attributes completion (#754) - - -## 3.1.0 (2023-07-11) +== 3.1.0 (2023-07-11) First stable release of 3.x which includes all changes from 3.0.x. -### Improvements +=== Improvements -- provide folding for list of sibling attributes by @apupier (#719) -- support remote includes when exporting in PDF without additional setting configuration (#731) +* provide folding for list of sibling attributes by @apupier (#719) +* support remote includes when exporting in PDF without additional setting configuration (#731) -### Bug fixes +=== Bug fixes -- folding of several single line comments is not working for more than 2 lines (#722) -- attribute coming from include files are missing in completion with 3.0.x (#727) +* folding of several single line comments is not working for more than 2 lines (#722) +* attribute coming from include files are missing in completion with 3.0.x (#727) +== 3.0.5 "pre-release" (2023-06-03) -## 3.0.5 "pre-release" (2023-06-03) +=== Breaking changes -### Breaking changes - -- use vscode fs api instead of Node fs by @apupier in https://github.com/asciidoctor/asciidoctor-vscode/pull/669 -- `pdf-themesdir` is now relative to the working directory (i.e., workspace folder) not relative to the document (#703) -- remove Asciidoctor CLI support (#539) -- `stylesdir` and `stylesheet` attributes are now _ignored_ in the preview. Instead, you should define `asciidoc.preview.style`. +* use vscode fs api instead of Node fs by @apupier in https://github.com/asciidoctor/asciidoctor-vscode/pull/669 +* `pdf-themesdir` is now relative to the working directory (i.e., workspace folder) not relative to the document (#703) +* remove Asciidoctor CLI support (#539) +* `stylesdir` and `stylesheet` attributes are now _ignored_ in the preview. Instead, you should define `asciidoc.preview.style`. Please note that when exporting to HTML, `stylesdir` and `stylesheet` will be used and should be defined in an `.asciidoctorconfig` file. -**NOTE:** We strongly recommend to use [`.asciidoctorconfig` file](https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html) to define common attributes. +*NOTE:* We strongly recommend to use https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html[`.asciidoctorconfig` file] to define common attributes. This file will be used in the preview and when exporting to HTML and PDF (using `asciidoctor-pdf`). -### Improvements +=== Improvements -- Include path to completion item for xref by @apupier in https://github.com/asciidoctor/asciidoctor-vscode/pull/671 -- add ability for asciidocParser to pass the krokiServerUrl by @haydencbarnes in https://github.com/asciidoctor/asciidoctor-vscode/pull/701 -- provide completion short hand and long hand notation with similar scope of legacy by @apupier in https://github.com/asciidoctor/asciidoctor-vscode/pull/668 -- append AsciiDoc attributes defined in antora.yml by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/694 -- add UI message with Japanese locale by @YoshihideShirai in https://github.com/asciidoctor/asciidoctor-vscode/pull/689 -- support non-Git workspace by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/696 -- provide completion after< Recommendations in snippets by @apupier -- fix release automation -- fix autocompletion on files (by replacing `.md` by `.adoc`) -- allow loading local resources from all workspace folders -- fix extensions loading on Windows (using `fsPath` otherwise Node require doesn't work on Windows) https://github.com/asciidoctor/asciidoctor-vscode/pull/630 -- fix show preview/preview localization by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/640 +* fix the logic that detects if `asciidoctor-pdf` and/or `bundler` are available in the `PATH` +* fix base directory when exporting to PDF on Windows (#593) +* fix localization generation by @YoshihideShirai (#594) +* fix Table Of Content sidebar color not aligned with the active theme by @apupier (#340) +* fix typo Recomendations \-> Recommendations in snippets by @apupier +* fix release automation +* fix autocompletion on files (by replacing `.md` by `.adoc`) +* allow loading local resources from all workspace folders +* fix extensions loading on Windows (using `fsPath` otherwise Node require doesn't work on Windows) https://github.com/asciidoctor/asciidoctor-vscode/pull/630 +* fix show preview/preview localization by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/640 -### Infrastructure +=== Infrastructure -- improve pull request and issue templates by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/633 -- add renovate config by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/657 +* improve pull request and issue templates by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/633 +* add renovate config by @ggrossetie in https://github.com/asciidoctor/asciidoctor-vscode/pull/657 -### Documentation +=== Documentation -- fix 2 small typos in readme by @apupier in https://github.com/asciidoctor/asciidoctor-vscode/pull/642 -- add an introduction and a prerequisite section. by @ahus1 in https://github.com/asciidoctor/asciidoctor-vscode/pull/656 +* fix 2 small typos in readme by @apupier in https://github.com/asciidoctor/asciidoctor-vscode/pull/642 +* add an introduction and a prerequisite section. by @ahus1 in https://github.com/asciidoctor/asciidoctor-vscode/pull/656 -## 3.0.0 "pre-release" (2022-07-06) - @ggrossetie +== 3.0.0 "pre-release" (2022-07-06) - @ggrossetie -### Improvements +=== Improvements -- add Japanese localisation by @YoshihideShirai (#581) -- register Asciidoctor.js extensions by @YoshihideShirai (#569) -- create a complete HTML document using the WebView converter by @ggrossetie (#547) -- add code folding based on sections by @marieflorescontact (#550) -- add code folding on conditionals by @marieflorescontact (#555) -- add code folding on open blocks by @marieflorescontact (#559) -- add code folding on comment blocks by @marieflorescontact (#561) -- add code folding on single line comment by @marieflorescontact (#565) -- update preview icons and use codicons by @ggrossetie (#54) -- use load instead of convert for performance by @ggrossetie (#542) -- normalize setting names and group settings by category by @ggrossetie (#577) -- do not offer to download an outdated version of `wkhtmltopdf` by @ggrossetie (#577) -- add a new setting to add command line arguments for `wkhtmltopdf` by @ggrossetie (#577) -- offer to install locally the latest version of `asciidoctor-pdf` by @ggrossetie (#577) +* add Japanese localisation by @YoshihideShirai (#581) +* register Asciidoctor.js extensions by @YoshihideShirai (#569) +* create a complete HTML document using the WebView converter by @ggrossetie (#547) +* add code folding based on sections by @marieflorescontact (#550) +* add code folding on conditionals by @marieflorescontact (#555) +* add code folding on open blocks by @marieflorescontact (#559) +* add code folding on comment blocks by @marieflorescontact (#561) +* add code folding on single line comment by @marieflorescontact (#565) +* update preview icons and use codicons by @ggrossetie (#54) +* use load instead of convert for performance by @ggrossetie (#542) +* normalize setting names and group settings by category by @ggrossetie (#577) +* do not offer to download an outdated version of `wkhtmltopdf` by @ggrossetie (#577) +* add a new setting to add command line arguments for `wkhtmltopdf` by @ggrossetie (#577) +* offer to install locally the latest version of `asciidoctor-pdf` by @ggrossetie (#577) -### Bug fixes +=== Bug fixes -- set `basebackend` and `outfilesuffix` on the WebView converter otherwise Docinfo are not correctly included (#522) -- activate completion only when `:` is at the start of the line by @ggrossetie (#529) -- correctly pass the `--footer-center` option to `wkthtmltopdf` by @gurbindersingh (#526) -- fix asciidoctor-pdf and wkhtmltopdf user settings by @meznom (#533) -- set CSS variables for font size, font family and line height by @ggrossetie (#530) -- fix format of paste image default filename by @Zhou-Yicheng (#558) -- show source action does not open a new pane (if the source is already opened) by @marieflorescontact (#562) -- fix for opening links to local files in preview window by @tombolano & @marieflorescontact (#572 #573) +* set `basebackend` and `outfilesuffix` on the WebView converter otherwise Docinfo are not correctly included (#522) +* activate completion only when `:` is at the start of the line by @ggrossetie (#529) +* correctly pass the `--footer-center` option to `wkthtmltopdf` by @gurbindersingh (#526) +* fix asciidoctor-pdf and wkhtmltopdf user settings by @meznom (#533) +* set CSS variables for font size, font family and line height by @ggrossetie (#530) +* fix format of paste image default filename by @Zhou-Yicheng (#558) +* show source action does not open a new pane (if the source is already opened) by @marieflorescontact (#562) +* fix for opening links to local files in preview window by @tombolano & @marieflorescontact (#572 #573) -### Infrastructure +=== Infrastructure -- upgrade dependencies (#515) -- extract the report errors logic into a dedicated function by @ggrossetie (#534) -- extract get baseDir logic by @ggrossetie (#535) -- remove superfluous `copycss` by @ggrossetie (#538) -- unwrap convertUsingJavascript function by @ggrossetie (#537) -- introduce a load function by @ggrossetie (#541) -- remove slugifier (unused) from AsciidocEngine by @ggrossetie (#545) -- introduce an export function by @ggrossetie (#546) +* upgrade dependencies (#515) +* extract the report errors logic into a dedicated function by @ggrossetie (#534) +* extract get baseDir logic by @ggrossetie (#535) +* remove superfluous `copycss` by @ggrossetie (#538) +* unwrap convertUsingJavascript function by @ggrossetie (#537) +* introduce a load function by @ggrossetie (#541) +* remove slugifier (unused) from AsciidocEngine by @ggrossetie (#545) +* introduce an export function by @ggrossetie (#546) -### Documentation +=== Documentation -- add basic instructions on how to develop/test the extension by @danyill (#540) -- fix manual install command in README by @marieflorescontact (#544) -- update contributing guide by @ggrossetie (#554) +* add basic instructions on how to develop/test the extension by @danyill (#540) +* fix manual install command in README by @marieflorescontact (#544) +* update contributing guide by @ggrossetie (#554) -## 2.9.8 +== 2.9.8 -- Fix regression about Docinfo files by setting `basebackend` and `outfilesuffix` (#524) -- Upgrade dependencies (#515) -- Fix regression about footer in the PDF export (#528) -- Only activate completion when `:` is at the start of the line (#529) -- Fix regression about reading `asciidoctorpdf_command` configuration (#533) -- Fix regression about reading `wkhtmltopdf_path` configuration (#533) +* Fix regression about Docinfo files by setting `basebackend` and `outfilesuffix` (#524) +* Upgrade dependencies (#515) +* Fix regression about footer in the PDF export (#528) +* Only activate completion when `:` is at the start of the line (#529) +* Fix regression about reading `asciidoctorpdf_command` configuration (#533) +* Fix regression about reading `wkhtmltopdf_path` configuration (#533) -## 2.9.5 +== 2.9.5 -- Fix regression in the PDF export (#512) -- Restructure the PDF export logic for testing (#512) -- Reduce bundle size (#517) -- Register the custom converter as `webview-html5` instead of replacing the built-in one `html5` (#513) +* Fix regression in the PDF export (#512) +* Restructure the PDF export logic for testing (#512) +* Reduce bundle size (#517) +* Register the custom converter as `webview-html5` instead of replacing the built-in one `html5` (#513) -## 2.9.4 +== 2.9.4 -- Fix regression in default preview styling (#501) -- Upgrade Asciidoctor.js to 2.2.6 (#514) +* Fix regression in default preview styling (#501) +* Upgrade Asciidoctor.js to 2.2.6 (#514) -## 2.9.3 +== 2.9.3 -- Build the web extension when packaging (#500) +* Build the web extension when packaging (#500) -## 2.9.2 +== 2.9.2 -- Initial work to make the extension available as a Web Extension (#473) -- Scroll to the first line when the preview hits top (closes #348) -- Removed a double word, add some colons for clarity, and puctuation in README.md (#483) -- Support hyperlinks in source pane for include directive (#498) +* Initial work to make the extension available as a Web Extension (#473) +* Scroll to the first line when the preview hits top (closes #348) +* Removed a double word, add some colons for clarity, and puctuation in README.md (#483) +* Support hyperlinks in source pane for include directive (#498) -## 2.8.10 +== 2.8.10 -- Ensure Asciidoctor.js error reporting is displayed on Windows (closes #466) -- Provide offline and integrated code syntax highlighting with highlight.js (closes #459) -- Update preview on preferences change (closes #447) -- Enforce code style (closes #446) -- Make `use_kroki` setting change effective without VS code restart (closes #444) -- Allow links to work in the preview pane (closes #435) -- Update Asciidoctor.js to 2.2.5 (closes #431) -- Upgrade asciidoctor-kroki to allow use of pikchr diagrams (closes #419) -- Allow chapter to start from zero (closes #415) -- Fix options link in README.md (closes #405) +* Ensure Asciidoctor.js error reporting is displayed on Windows (closes #466) +* Provide offline and integrated code syntax highlighting with highlight.js (closes #459) +* Update preview on preferences change (closes #447) +* Enforce code style (closes #446) +* Make `use_kroki` setting change effective without VS code restart (closes #444) +* Allow links to work in the preview pane (closes #435) +* Update Asciidoctor.js to 2.2.5 (closes #431) +* Upgrade asciidoctor-kroki to allow use of pikchr diagrams (closes #419) +* Allow chapter to start from zero (closes #415) +* Fix options link in README.md (closes #405) -## 2.8.9 +== 2.8.9 -- Fix links in preview (closes #397) +* Fix links in preview (closes #397) -## 2.8.8 +== 2.8.8 -- updated asciidoc-kroki to 0.12.0 -- allow use of ${workspaceFolder} in attributes -- provide import completion for include and images +* updated asciidoc-kroki to 0.12.0 +* allow use of $\{workspaceFolder} in attributes +* provide import completion for include and images -## 2.8.7 +== 2.8.7 -- update asciidoc-kroki to v0.11.0 +* update asciidoc-kroki to v0.11.0 -## 2.8.4 +== 2.8.4 -- Fix "TypeError: range must be set" when previewing (closes #364) -- Bump lodash from 4.17.15 to 4.17.19 closes (#354) +* Fix "TypeError: range must be set" when previewing (closes #364) +* Bump lodash from 4.17.15 to 4.17.19 closes (#354) -## 2.8.3 +== 2.8.3 * Fix unexpected splitting multibyte chars while chunking (closes #350) * Fixed default export PDF filename when using asciidoctorpdf (closes #349) -## 2.8.2 +== 2.8.2 * Remove depdendency on "copy-paste" which is never used -## 2.8.1 +== 2.8.1 * No changes, release/publish using GitHub Actions -## 2.8.0 +== 2.8.0 * Provide a safer default and configurable refresh interval (closes #334) -## 2.7.20 +== 2.7.20 * Replace all references from joaompinto.asciidoctor-vscode to asciidoctor.asciidoctor-vscode -## 2.7.19 +== 2.7.19 * Updated the extension path retrieval to use the new asciidoctor publisher * Updated the demo gif -## 2.7.18 +== 2.7.18 * Add "vsce" as a development dependency * Fix problem creating .pdf with v2.7.16 (closes #332) * Move wkhtmltopdf binaries to their own repository - -## 2.7.17 +== 2.7.17 * Add "vsce" as a development dependency * Fix problem creating .pdf with v2.7.16 (closes #331) * Provide diagnostics information for asciidoctor errors (PR #329) - -## 2.7.16 +== 2.7.16 * Update asciidoctor-kroki to 0.9.1 * Remove asciidoctor-plantuml «out of maintenance» (closes #308) @@ -388,38 +375,38 @@ This file will be used in the preview and when exporting to HTML and PDF (using * Added the ability to use the workspace path as the base_dir (closes #326) * Added eslint validation (closes #290) -## 2.7.15 +== 2.7.15 * Align the "Export to PDF" to the "Save as HTML" (closes #298) * Support URI encoded characters in anchors links (closes #281) * Add env-vscode attribute to detect vs code environment (closes #280) -## 2.7.14 +== 2.7.14 * Add support for saving to Docbook (closes #102) -## 2.7.13 +== 2.7.13 * Fix Save HTML file path on Windows (closes #269) * Remove viz.js, let kroki handle graphviz (closes #267) -## 2.7.12 +== 2.7.12 * Add support for saving html output -## 2.7.11 +== 2.7.11 * Add Ctrl+Alt+V/Cmd+Alt+V (Mac) as shortcut key for image paste -## 2.7.10 +== 2.7.10 -* Change language definition to be the same as that of the Atom extension [atom-language-asciidoc](https://github.com/asciidoctor/atom-language-asciidoc/) +* Change language definition to be the same as that of the Atom extension https://github.com/asciidoctor/atom-language-asciidoc/[atom-language-asciidoc] * Support the source block (closes #212) * Support image pasting on Linux/Mac (closes #255) * Add Ctrl+Alt+V/Cmd+Alt+V (Mac) as shortcut key for image paste * Add `.png` extension automatically for image pasting -## 2.7.9 +== 2.7.9 * Prevent table of contents overlapping document for `:toc: left` and `:toc: right` (closes #141) * Provide Intellisense autocomplete for attributes @@ -430,193 +417,193 @@ This file will be used in the preview and when exporting to HTML and PDF (using * Revise asciidoctor-pdf command to prepare for use of asciidoctor-pdf.js * Tidy up licensing and copyright notices in files -## 2.7.8 +== 2.7.8 * Disable foldingProvider and add throttling to SymbolProvider * Add asciidoctor-kroki support -## 2.7.7 +== 2.7.7 * Add basic symbol provider (closes #234) * Clean use of '-o' option for compatibility with asciidoctorj (closes #232) -## 2.7.6 +== 2.7.6 * Add config option to set the wkhtmltopdf binary path (closes #202) -## 2.7.5 +== 2.7.5 * Update Asciidoctor(.JS) requirement to 2.0.3 (fixes #203, thanks to @jvalkeal) -## 2.7.4 +== 2.7.4 * Fixes: No autoscroll in VSCode > 1.28 #182 -## 2.7.3 +== 2.7.3 -* Fixes to README (thanks to @jstafman ) +* Fixes to README (thanks to @jstafman link:mailto:jstafman@protonmail.com[jstafman@protonmail.com]) * Changed the order of configuration settings * Display an error notification when asciidoctor.js fails -## 2.7.2 +== 2.7.2 * Fix an error caused by incorrectly accessing the workspace folder (issue #191) -## 2.7.1 +== 2.7.1 * Fix `preview.attributes` description. -## 2.7.0 +== 2.7.0 * Add `preview.style` option to set preview stylesheet in settings -## 2.6.0 +== 2.6.0 * Add `preview.attributes` option to set preview attributes in the user/workspace settings * Overhaul README -## 2.5.2 +== 2.5.2 -* Fix an error from [2.5.1](#2.5.1) that caused all syntax highlighting to fail +* Fix an error from <<2.5.1,2.5.1>> that caused all syntax highlighting to fail -## 2.5.1 +== 2.5.1 * Change remaining Markdown-named variables/modules to AsciiDoc * Improve automated building/packaging script -* Fix contrained literal (\`) or closing single typographic quote (\`') bug when used inside typographic quotes (e.g. "\`busy \`'till tomorrow\`" would create a recursive match) -* Add syntax highlight for closing single typographic quote (\`') +* Fix contrained literal (`) or closing single typographic quote (`') bug when used inside typographic quotes (e.g. "`busy `'till tomorrow`" would create a recursive match) +* Add syntax highlight for closing single typographic quote (`') -## 2.5.0 +== 2.5.0 * Repaired preview.useEditorStyle option * Improved the editor-style css to match the default one used by asciidoctor -## 2.4.1 +== 2.4.1 -* Fix missing highlight for single character constrained inlines (e.g. \*a\*) +* Fix missing highlight for single character constrained inlines (e.g. *a*) -## 2.4.0 +== 2.4.0 * Fix errors with the preview security setting -* Fix an error with jsonValidation (thanks to @shaneknysh ) -* Fix descriptions still using "Markdown" instead of "AsciiDoc" (thanks to @ygra ) -* Update preview to ascidoctor.js v1.5.9 (thanks to @ggrossetie ) -* Fix encoding errors (thanks to @mojavelinux ) +* Fix an error with jsonValidation (thanks to @shaneknysh link:mailto:shane.knysh@gmail.com[shane.knysh@gmail.com]) +* Fix descriptions still using "Markdown" instead of "AsciiDoc" (thanks to @ygra link:mailto:joey@muhkuhsaft.de[joey@muhkuhsaft.de]) +* Update preview to ascidoctor.js v1.5.9 (thanks to @ggrossetie link:mailto:ggrossetie@gmail.com[ggrossetie@gmail.com]) +* Fix encoding errors (thanks to @mojavelinux link:mailto:dan.j.allen@gmail.com[dan.j.allen@gmail.com]) -## 2.3.3 +== 2.3.3 -* Fix plantUML preview from multiple files and folders (thanks to @Dimeiza ) +* Fix plantUML preview from multiple files and folders (thanks to @Dimeiza link:mailto:dimeiza@hotmail.com[dimeiza@hotmail.com]) -## 2.3.2 +== 2.3.2 * Highlight fenced source blocks (Markdown-like syntax) in the editor -## 2.3.1 +== 2.3.1 * Add snippets for general attribute and tagged block * Temporary fix for transparent side toc (`:toc: left`, `:toc: right`) -## 2.3.0 +== 2.3.0 * Add option to use asciidoctor-pdf instead of wkhtmltopdf * Fix pdf paths with single quotes not opening from the notification after exportAsPDF -## 2.2.0 +== 2.2.0 * Fix documents with apostrophe in path not rendering with manual command * Add option to use editor or default style in preview * Snippets -## 2.1.1 +== 2.1.1 * Use theme background on preview (thanks to matteo.campinoti94@gmail.com) * Broken links on diagrams in preview (asciidoc.use_asciidoctor_js: false), closes #142 -## 2.1.0 +== 2.1.0 * YAML syntax file, improved inline syntax detection, automated building (thanks to matteo.campinoti94@gmail.com) * fixes typos in Description for AsciiDoc.forceUnixStyleSeparator (thanks to ccb012100) * diagram (specifically plantUML) support in asciidoctor.js (closes #105) -## 1.0.99 +== 1.0.99 * Rebuilt using vscode-1.28.2/extensions/markdown* from Microsoft -## 1.0.x +== 1.0.x * Test release -## 0.15.1 +== 0.15.1 * asciidoctor_command can have arguments (closes #103) * updated fs-extra requirements (closes #88) -## 0.15.0 +== 0.15.0 * Support for copy/paste images -## 0.14.0 +== 0.14.0 * Style/Disable Preview Highlighting (closes #85) -## 0.13.0 +== 0.13.0 * Add support for Mermaid Diagrams (unprintable) -## 0.12.0 +== 0.12.0 * Add graphviz support using Viz.js (closes #78) -## 0.11.2 +== 0.11.2 * Support :footer-center: to place a footer center on exported PDF (closes #77) -## 0.11.1 +== 0.11.1 * Removed unnecessary binary files from the extension package -## 0.11.0 +== 0.11.0 * Improve the default CSS (closes #76) * Add page break support for PDF export (closes #75) -## 0.10.0 +== 0.10.0 * Support logo on title page (closes #74) -## 0.9.1 +== 0.9.1 * Rename CHANGES.md CHANGELOG.md to have it shown in the extension info -## 0.9.0 +== 0.9.0 * Quote filename on asciidoctor call (closes #73) * Added title page with author info (closes #71) -* Added Technical Document snippet, based on +* Added Technical Document snippet, based on http://web.mit.edu/course/21/21.guide/elemtech.htm -## 0.8.0 +== 0.8.0 * wordwrap if the file type is .adoc (closes #65) * activate on "asciidoc" related commands (closes #64) -## 0.7.2 +== 0.7.2 * runInterval is now respected during document changes (closes #68) -## 0.7.1 +== 0.7.1 * Fix links when using external asciidoctor (closes #67) -## 0.7.0 +== 0.7.0 * Added Export to PDF command (using wkhtmltopdf) -## 0.6.0 +== 0.6.0 * Synchronize preview with the selected/edited source line * The preview window is now shared accross documents -## 0.5.0 +== 0.5.0 * Use asciidoctor with -q since we now rely on stderr for error detection * On settings replaced html_generator with asciidoctor_command @@ -626,23 +613,23 @@ This file will be used in the preview and when exporting to HTML and PDF (using * Merge pull request #53 from malvim/formatting-surround * Enable auto surrounding for formatting symbols -## 0.4.3 +== 0.4.3 * Always rebuild preview when preview uri changes, closes #43 -## 0.4.2 +== 0.4.2 * Use `convertFile()` instead off `Convert()`, closes #50 -## 0.4.1 +== 0.4.1 * Fixed the "how to install" instructions -## 0.4.0 +== 0.4.0 * Use Asciidoctor.js by default (setting AsciiDoc.use_asciidoctor_js = true), closes #29 -## 0.3.8 +== 0.3.8 * Added symbol view, closes #3 * Keyboard binding changed to `ctrl+shift+r` (Mac: `cmd+shift+r`) @@ -651,30 +638,30 @@ This file will be used in the preview and when exporting to HTML and PDF (using * Added buffer size parameter for larger Asciidoc rendering capability * Support # symbol as section header -## 0.3.5 - 0.3.7 +== 0.3.5 - 0.3.7 -## 0.3.3 +== 0.3.3 * Do not prefix links for local #sections -## 0.3.2 +== 0.3.2 * Apply fixLinks to local links, closes #12 -## 0.3.1 +== 0.3.1 * Removed broken fixLinks transformation (this closes #6, closes #10) -## 0.3.0 +== 0.3.0 * Use time based preview refresh instead of on document change, this closes #9 * Major code reorganization and documentation -## 0.2.1 +== 0.2.1 * Quote filename when invoking asciidoctor, this closes #4 -## 0.2.0 +== 0.2.0 * Added full error message display when asciidoctor execution fails * Improved samples with CSS and icons diff --git a/README.adoc b/README.adoc index 65e9ccfd..c24b7d1c 100644 --- a/README.adoc +++ b/README.adoc @@ -1,15 +1,15 @@ -# AsciiDoc support for Visual Studio Code += AsciiDoc support for Visual Studio Code -[![Version](https://img.shields.io/visual-studio-marketplace/v/asciidoctor.asciidoctor-vscode)](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) -[![Installs](https://img.shields.io/visual-studio-marketplace/i/asciidoctor.asciidoctor-vscode)](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) -[![Ratings](https://img.shields.io/visual-studio-marketplace/r/asciidoctor.asciidoctor-vscode)](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) -[![Project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.png)](https://chat.asciidoctor.org/) +image:https://img.shields.io/visual-studio-marketplace/v/asciidoctor.asciidoctor-vscode[Version,link=https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode] +image:https://img.shields.io/visual-studio-marketplace/i/asciidoctor.asciidoctor-vscode[Installs,link=https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode] +image:https://img.shields.io/visual-studio-marketplace/r/asciidoctor.asciidoctor-vscode[Ratings,link=https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode] +image:https://img.shields.io/badge/zulip-join_chat-brightgreen.png[Project chat,link=https://chat.asciidoctor.org/] An extension that provides live preview, syntax highlighting and snippets for the AsciiDoc format using Asciidoctor. -![demo](images/simple.gif) +image::images/simple.gif[demo] -## How to Install +== How to Install Launch Visual Studio Code "Quick Open" (`Ctrl+P`), paste the following command, and press `Enter`: @@ -17,27 +17,58 @@ Launch Visual Studio Code "Quick Open" (`Ctrl+P`), paste the following command, Alternatively, you can use the built-in extension browser to find the _AsciiDoc_ by _asciidoctor_ extension and install it. -This extension is also available as a pre-version (alpha) in [Visual Studio Code for the Web](https://code.visualstudio.com/docs/editor/vscode-web) +This extension is also available as a pre-version (alpha) in https://code.visualstudio.com/docs/editor/vscode-web[Visual Studio Code for the Web] and can be installed using the same procedure. -|Feature|Desktop|Web| -|--|--|--| -|Document Outline and Symbols|✔️|✔️| -|Equations (via Mathjax)|✔️|✔️ (requires security to be disabled)| -|Export as PDF|✔️|⛔| -|Kroki Integration for Diagrams|✔️|✔️| -|Paste Image |✔️|⛔| -|Save as HTML|✔️|⛔| -|Save as DocBook|✔️|⛔| -|Snippets|✔️|✔️| -|Syntax Highlighting|✔️|✔️ (requires security to be disabled)| -|Sync scrolling between the editor and the preview|✔️|✔️| - -## How to Use +|=== +| Feature | Desktop | Web + +| Document Outline and Symbols +| ✔️ +| ✔️ + +| Equations (via Mathjax) +| ✔️ +| ✔️ (requires security to be disabled) + +| Export as PDF +| ✔️ +| ⛔ + +| Kroki Integration for Diagrams +| ✔️ +| ✔️ + +| Paste Image +| ✔️ +| ⛔ + +| Save as HTML +| ✔️ +| ⛔ + +| Save as DocBook +| ✔️ +| ⛔ + +| Snippets +| ✔️ +| ✔️ + +| Syntax Highlighting +| ✔️ +| ✔️ (requires security to be disabled) + +| Sync scrolling between the editor and the preview +| ✔️ +| ✔️ +|=== + +== How to Use The extension activates automatically when opening an AsciiDoc file (.adoc, .ad, .asc, .asciidoc). -### Preview +=== Preview To show the preview you can use the same commands as the Markdown extension: @@ -50,11 +81,11 @@ The preview supports setting AsciiDoc attributes through the `asciidoc.preview.a By default, the preview uses VS Code editor theme (`workbench.colorTheme`). To use Asciidoctor default style set the `asciidoc.preview.useEditorStyle` setting to `false`. -It is possible to set your own preview stylesheet with the `asciidoc.preview.style` setting.
-It is also possible to define custom templates with the `asciidoc.preview.templates` setting.
-(See more details under [Extension Settings](#extension-settings)) +It is possible to set your own preview stylesheet with the `asciidoc.preview.style` setting. + +It is also possible to define custom templates with the `asciidoc.preview.templates` setting. + +(See more details under <>) -### Export as PDF +=== Export as PDF The extension provides a quick command to export your AsciiDoc file as PDF. @@ -63,10 +94,10 @@ The extension provides a quick command to export your AsciiDoc file as PDF. * Choose the folder and filename for the generated PDF By default, the PDF export feature relies on `asciidoctor-pdf`. -If you prefer to use `wkhtmltopdf`, set the `asciidoc.pdf.engine` setting to `wkhtmltopdf` and configure the `asciidoc.pdf.wkhtmltopdfCommandPath` if necessary.
-(See more details under [Extension Settings](#extension-settings)) +If you prefer to use `wkhtmltopdf`, set the `asciidoc.pdf.engine` setting to `wkhtmltopdf` and configure the `asciidoc.pdf.wkhtmltopdfCommandPath` if necessary. + +(See more details under <>) -### Save as HTML +=== Save as HTML The extension provides a quick command to export your AsciiDoc file as HTML using the default Asciidoctor stylesheet. @@ -76,7 +107,7 @@ The extension provides a quick command to export your AsciiDoc file as HTML usin The shortcut key of `ctrl+alt+s` (Mac: `cmd+alt+s`) will also save the document. -### Save to Docbook +=== Save to Docbook The extension provides a quick command to export your AsciiDoc file as DocBook. @@ -84,40 +115,41 @@ The extension provides a quick command to export your AsciiDoc file as DocBook. * Select _AsciiDoc: Save to DocBook_ * The file is generated in the same folder as the source document -**ℹ️ Note:** Only DocBook 5 is supported. +*ℹ️ Note:* Only DocBook 5 is supported. -### Snippets +=== 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_. -### Identifying the VS Code Environment +=== 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: -```asciidoc +[,asciidoc] +---- ifdef::env-vscode[] This is for vscode only endif::[] -``` +---- -### Diagram Integration +=== Diagram Integration -This extension supports a wide range of diagrams from BPMN to Graphviz to PlantUML and Vega graphs using [Kroki](https://kroki.io/) -and [asciidoctor-kroki](https://github.com/Mogztter/asciidoctor-kroki). +This extension supports a wide range of diagrams from BPMN to Graphviz to PlantUML and Vega graphs using https://kroki.io/[Kroki] +and https://github.com/Mogztter/asciidoctor-kroki[asciidoctor-kroki]. -You can [see the full range](https://kroki.io/#support) on the Kroki website. +You can https://kroki.io/#support[see the full range] on the Kroki website. -Note that this extension will send graph information to . -If this is an issue it is also possible to use your own Kroki instance (see [the instructions](https://github.com/Mogztter/asciidoctor-kroki#using-your-own-kroki) for further information). +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 https://github.com/Mogztter/asciidoctor-kroki#using-your-own-kroki[the instructions] for further information). To enable diagram support, set the `asciidoc.extensions.enableKroki` setting to `true`. -**❗ Important:** Please note that `:kroki-fetch-diagram:` is currently not supported because it relies on `unxhr` which does not work in VS Code (https://github.com/ggrossetie/unxhr/issues/98). +*❗ Important:* Please note that `:kroki-fetch-diagram:` is currently not supported because it relies on `unxhr` which does not work in VS Code (https://github.com/ggrossetie/unxhr/issues/98). -### Use Asciidoctor.js extensions +=== Use Asciidoctor.js extensions When using the preview, the VS Code extension can load and register Asciidoctor.js extensions. @@ -128,121 +160,198 @@ For instance, the following files will be loaded: `.asciidoctor/lib/emoji.js`, ` To use an Asciidoctor.js extension, you should enable the feature by checking "Enable Asciidoctor.js extensions registration" in the extension settings. The first time, you will also need to confirm that you trust the authors of the Asciidoctor.js extensions located in _.asciidoctor/lib_. -![Asciidoctor.js extensions trust confirmation message](images/asciidoctor-vscode-trust-exts.png) +image::images/asciidoctor-vscode-trust-exts.png[Asciidoctor.js extensions trust confirmation message] -**❗ Important:** This feature will execute JavaScript code and should not be enabled if you don't fully trust the authors of the Asciidoctor.js extensions. +*❗ Important:* This feature will execute JavaScript code and should not be enabled if you don't fully trust the authors of the Asciidoctor.js extensions. -**💡 Tip:** You can always update the trust mode using the command "Manage Asciidoctor.js Extensions Trust Mode". +*💡 Tip:* You can always update the trust mode using the command "Manage Asciidoctor.js Extensions Trust Mode". You can create a new extension by creating a JavaScript file in the `.asciidoctor/lib` directory or use an existing one. -Here's an example of how to use the [asciidoctor-emoji](https://github.com/mogztter/asciidoctor-emoji) extension: - -1. Install the npm package in the workspace directory: +Here's an example of how to use the https://github.com/mogztter/asciidoctor-emoji[asciidoctor-emoji] extension: - ```shell - npm i asciidoctor-emoji - ``` +. Install the npm package in the workspace directory: ++ +[,shell] +---- + npm i asciidoctor-emoji +---- -2. Create a file a JavaScript file in _.asciidoctor/lib_ with the following content: +. Create a file a JavaScript file in _.asciidoctor/lib_ with the following content: ++ +[,javascript] +---- + module.exports = require('asciidoctor-emoji') +---- - ```javascript - module.exports = require('asciidoctor-emoji') - ``` +. Enjoy :tada: -3. Enjoy :tada: +image::images/asciidoctor-vscode-emoji-ext.png[Asciidoctor.js Emoji extension enabled!] -![Asciidoctor.js Emoji extension enabled!](images/asciidoctor-vscode-emoji-ext.png) - -### Asciidoctor Config File +=== Asciidoctor Config File To provide a common set of variables when rendering the preview, the extension reads an `.asciidoctorconfig` or `.asciidoctorconfig.adoc` configuration file. Use this to optimize the preview when the project contains a document that is split out to multiple include-files. -It is inspired by the implementation provided in [IntelliJ AsciiDoc Plugin](https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html) and reused in [Eclipse AsciiDoc plugin](https://github.com/de-jcup/eclipse-asciidoctor-editor/wiki/Asciidoctor-configfiles). +It is inspired by the implementation provided in https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html[IntelliJ AsciiDoc Plugin] and reused in https://github.com/de-jcup/eclipse-asciidoctor-editor/wiki/Asciidoctor-configfiles[Eclipse AsciiDoc plugin]. -## Extension Settings +== Extension Settings This extension contributes the following settings: -### Preview +=== Preview + +|=== +| Name | Description | Default Value + +| `asciidoc.preview.asciidoctorAttribute` +| Asciidoctor attributes used in the preview (object of `{string: string}`). +| `{}` + +| `asciidoc.preview.refreshInterval` +| Interval in milliseconds between two consecutive updates of the preview. The value 0 means it will only update the preview on save. +| `2000` + +| `asciidoc.preview.style` +| An URL or a local path to CSS style sheets to use from the preview. +| + +| `asciidoc.preview.useEditorStyle` +| Use VS Code editor style instead of the default Asciidoctor style. +| + +| `asciidoc.preview.fontFamily` +| Control the font family used in the preview. +| `"-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'HelveticaNeue-Light', 'Ubuntu', 'Droid Sans', sans-serif"` + +| `asciidoc.preview.fontSize` +| Control the font size in pixels used in the preview. +| `14` + +| `asciidoc.preview.lineHeight` +| Control the line height used in the preview. +| `1.6` + +| `asciidoc.preview.scrollPreviewWithEditor` +| When the preview is scrolled, update the view of the editor. +| `true` + +| `asciidoc.preview.scrollEditorWithPreview` +| When the editor is scrolled, update the view of the preview. +| `true` + +| `asciidoc.preview.markEditorSelection` +| Mark the current editor selection in the preview. +| `true` + +| `asciidoc.preview.doubleClickToSwitchToEditor` +| Double click in the preview to switch to the editor. +| `true` + +| `asciidoc.preview.preservePreviewWhenHidden` +| Keep the AsciiDoc preview in memory when it's hidden so that it reloads faster, at the expense of increased memory use. +| `false` + +| `asciidoc.preview.openLinksToAsciidocFiles` +| Control how links to other AsciiDoc files in the preview should be opened. Possible values: `"inPreview"`, `"inEditor"`. +| `"inPreview"` +|=== + +=== PDF + +|=== +| Name | Description | Default Value + +| `asciidoc.pdf.engine` +| Control the PDF engine used to export as PDF. Possible values: `"asciidoctor-pdf"`, `"wkhtmltopdf"`. +| `"asciidoctor-pdf"` + +| `asciidoc.pdf.asciidoctorPdfCommandPath` +| External `asciidoctor-pdf` command to execute. It accepts a full path to the binary, for instance: `/path/to/asciidoctor-pdf`. +| `"bundle exec asciidoctor-pdf"` + +| `asciidoc.pdf.asciidoctorPdfCommandArgs` +| List of arguments, for instance: `-a`, `pdf-themesdir=resources/themes`, `-a`, `pdf-theme=basic`. Please note that the argument key and value should be added separately (i.e., two items). By default, it passes the following arguments: `--quiet` and `--base-dir` with the full directory path to the AsciiDoc document. +| `[]` + +| `asciidoc.pdf.wkhtmltopdfCommandPath` +| External `wkhtmltopdf` command to execute. It accepts a full path to the binary, for instance: `/path/to/wkhtmltopdf`. If the value is empty, use either `wkhtmltopdf` on Linux/macOS or `wkhtmltopdf.exe` on Windows. +| `""` + +| `asciidoc.pdf.wkhtmltopdfCommandArgs` +| List of arguments, for instance: `--orientation`, `Landscape`. Please note that the argument key and value should be added separately (i.e., two items). By default, it passes the following arguments: `--enable-local-file-access`, `--encoding`, `utf-8`, `--javascript-delay`, `1000`, `--footer-center` (if enabled) and `cover` (if it has a cover page). +| `[]` +|=== + +=== Extensions + +|=== +| Name | Description | Default Value -| Name | Description | Default Value | -|:-----------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------| -| `asciidoc.preview.asciidoctorAttribute` | Asciidoctor attributes used in the preview (object of `{string: string}`). | `{}` | -| `asciidoc.preview.refreshInterval` | Interval in milliseconds between two consecutive updates of the preview. The value 0 means it will only update the preview on save. | `2000` | -| `asciidoc.preview.style` | An URL or a local path to CSS style sheets to use from the preview. | | -| `asciidoc.preview.useEditorStyle` | Use VS Code editor style instead of the default Asciidoctor style. | | -| `asciidoc.preview.fontFamily` | Control the font family used in the preview. | `"-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'HelveticaNeue-Light', 'Ubuntu', 'Droid Sans', sans-serif"` | -| `asciidoc.preview.fontSize` | Control the font size in pixels used in the preview. | `14` | -| `asciidoc.preview.lineHeight` | Control the line height used in the preview. | `1.6` | -| `asciidoc.preview.scrollPreviewWithEditor` | When the preview is scrolled, update the view of the editor. | `true` | -| `asciidoc.preview.scrollEditorWithPreview` | When the editor is scrolled, update the view of the preview. | `true` | -| `asciidoc.preview.markEditorSelection` | Mark the current editor selection in the preview. | `true` | -| `asciidoc.preview.doubleClickToSwitchToEditor` | Double click in the preview to switch to the editor. | `true` | -| `asciidoc.preview.preservePreviewWhenHidden` | Keep the AsciiDoc preview in memory when it's hidden so that it reloads faster, at the expense of increased memory use. | `false` | -| `asciidoc.preview.openLinksToAsciidocFiles` | Control how links to other AsciiDoc files in the preview should be opened. Possible values: `"inPreview"`, `"inEditor"`. | `"inPreview"` | +| `asciidoc.extensions.enableKroki` +| Enable Kroki extension to generate diagrams. +| `false` -### PDF +| `asciidoc.extensions.registerWorkspaceExtensions` +| Enables Asciidoctor.js extensions registration from the workspace directory `.asciidoctor/lib`. +| `false` +|=== -| Name | Description | Default Value | -|:-----------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------| -| `asciidoc.pdf.engine` | Control the PDF engine used to export as PDF. Possible values: `"asciidoctor-pdf"`, `"wkhtmltopdf"`. | `"asciidoctor-pdf"` | -| `asciidoc.pdf.asciidoctorPdfCommandPath` | External `asciidoctor-pdf` command to execute. It accepts a full path to the binary, for instance: `/path/to/asciidoctor-pdf`. | `"bundle exec asciidoctor-pdf"` | -| `asciidoc.pdf.asciidoctorPdfCommandArgs` | List of arguments, for instance: `-a`, `pdf-themesdir=resources/themes`, `-a`, `pdf-theme=basic`. Please note that the argument key and value should be added separately (i.e., two items). By default, it passes the following arguments: `--quiet` and `--base-dir` with the full directory path to the AsciiDoc document. | `[]` | -| `asciidoc.pdf.wkhtmltopdfCommandPath` | External `wkhtmltopdf` command to execute. It accepts a full path to the binary, for instance: `/path/to/wkhtmltopdf`. If the value is empty, use either `wkhtmltopdf` on Linux/macOS or `wkhtmltopdf.exe` on Windows. | `""` | -| `asciidoc.pdf.wkhtmltopdfCommandArgs` | List of arguments, for instance: `--orientation`, `Landscape`. Please note that the argument key and value should be added separately (i.e., two items). By default, it passes the following arguments: `--enable-local-file-access`, `--encoding`, `utf-8`, `--javascript-delay`, `1000`, `--footer-center` (if enabled) and `cover` (if it has a cover page). | `[]` | +=== General -### Extensions +|=== +| Name | Description | Default Value -| Name | Description | Default Value | -|:--------------------------------------------------|:------------------------------------------------------------------------------------------------|:--------------| -| `asciidoc.extensions.enableKroki` | Enable Kroki extension to generate diagrams. | `false` | -| `asciidoc.extensions.registerWorkspaceExtensions` | Enables Asciidoctor.js extensions registration from the workspace directory `.asciidoctor/lib`. | `false` | +| `asciidoc.useWorkspaceRootAsBaseDirectory` +| When in a workspace, use the workspace root path as the base directory. +| `false` +|=== -### General +=== Debug -| Name | Description | Default Value | -|:-------------------------------------------|:------------------------------------------------------------------------|:--------------| -| `asciidoc.useWorkspaceRootAsBaseDirectory` | When in a workspace, use the workspace root path as the base directory. | `false` | +|=== +| Name | Description | Default Value -### Debug +| `asciidoc.debug.trace` +| Enable debug logging for this extension. Possible values: `"off"`, `"verbose"`. +| `"off"` -| Name | Description | Default Value | -|:----------------------------------------|:--------------------------------------------------------------------------------|:--------------| -| `asciidoc.debug.trace` | Enable debug logging for this extension. Possible values: `"off"`, `"verbose"`. | `"off"` | -| `asciidoc.debug.enableErrorDiagnostics` | Provide error diagnostics. | `true` | +| `asciidoc.debug.enableErrorDiagnostics` +| Provide error diagnostics. +| `true` +|=== -## Build and Install from Source +== Build and Install from Source -### Manual +=== Manual -```shell +[,shell] +---- git clone https://github.com/asciidoctor/asciidoctor-vscode cd asciidoctor-vscode npm install npm run package code --install-extension *.vsix -``` +---- -## Issues +== 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](https://github.com/asciidoctor/asciidoctor-vscode/issues). +page: https://github.com/asciidoctor/asciidoctor-vscode/issues[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](https://github.com/asciidoctor/asciidoctor-vscode/issues?utf8=%E2%9C%93&q=). +solved: https://github.com/asciidoctor/asciidoctor-vscode/issues?utf8=%E2%9C%93&q=[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 screenshot that might better show what the issue is. +. Description of the issue +. VSCode version, OS (_Help \-> About_) and extension version +. Steps to reproduce the issue + +*IMPORTANT*: We cannot solve the issue if you do not explain how you encountered it +. If the problem occurs only with a specific file, attach it, together with any screenshot 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 +== Contributing To contribute simply clone the repository and then commit your changes. When you do a pull request please clearly highlight what you changed in the pull comment. @@ -251,11 +360,11 @@ Do not update the extension version or changelog, it will be done by the maintai If you want to update the readme, you are free to fix typos, errors, and 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 +== Credits -* [AsciiDoc](http://asciidoc.org/) by Stuart Rackham -* [Asciidoctor](https://asciidoctor.org/) organization for the language flavor -* [Asciidoctor.js](https://asciidoctor.org/docs/asciidoctor.js/) for the preview -* [Asciidoctor PDF](https://asciidoctor.org/docs/asciidoctor-pdf/) for the _Export to PDF_ function -* [wkhtmltopdf](https://wkhtmltopdf.org/) for the _Export to PDF_ function -* [Each and every contributor](https://github.com/asciidoctor/asciidoctor-vscode/graphs/contributors) to this extension. +* http://asciidoc.org/[AsciiDoc] by Stuart Rackham +* https://asciidoctor.org/[Asciidoctor] organization for the language flavor +* https://asciidoctor.org/docs/asciidoctor.js/[Asciidoctor.js] for the preview +* https://asciidoctor.org/docs/asciidoctor-pdf/[Asciidoctor PDF] for the _Export to PDF_ function +* https://wkhtmltopdf.org/[wkhtmltopdf] for the _Export to PDF_ function +* https://github.com/asciidoctor/asciidoctor-vscode/graphs/contributors[Each and every contributor] to this extension. From ba0208f69ae7f7c019f85c502ff89f2fb8ebd9dc Mon Sep 17 00:00:00 2001 From: Victor Toni Date: Mon, 11 Mar 2024 15:29:51 +0100 Subject: [PATCH 3/3] Minor manual adjustments for automatic conversion from Markdown --- README.adoc | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/README.adoc b/README.adoc index c24b7d1c..8590577a 100644 --- a/README.adoc +++ b/README.adoc @@ -1,4 +1,10 @@ = AsciiDoc support for Visual Studio Code +ifndef::env-github[:icons: font] +ifdef::env-github[] +:important-caption: :exclamation: +:note-caption: :paperclip: +:tip-caption: :bulb: +endif::[] image:https://img.shields.io/visual-studio-marketplace/v/asciidoctor.asciidoctor-vscode[Version,link=https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode] image:https://img.shields.io/visual-studio-marketplace/i/asciidoctor.asciidoctor-vscode[Installs,link=https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode] @@ -115,7 +121,10 @@ The extension provides a quick command to export your AsciiDoc file as DocBook. * Select _AsciiDoc: Save to DocBook_ * The file is generated in the same folder as the source document -*ℹ️ Note:* Only DocBook 5 is supported. +[NOTE] +==== +*Note*: Only DocBook 5 is supported. +==== === Snippets @@ -130,9 +139,9 @@ If you need to identify or handle the VS Code environment you can use an `ifdef` [,asciidoc] ---- -ifdef::env-vscode[] +\ifdef::env-vscode[] This is for vscode only -endif::[] +\endif::[] ---- === Diagram Integration @@ -147,7 +156,10 @@ If this is an issue it is also possible to use your own Kroki instance (see http To enable diagram support, set the `asciidoc.extensions.enableKroki` setting to `true`. -*❗ Important:* Please note that `:kroki-fetch-diagram:` is currently not supported because it relies on `unxhr` which does not work in VS Code (https://github.com/ggrossetie/unxhr/issues/98). +[IMPORTANT] +==== +*Important*: Please note that `:kroki-fetch-diagram:` is currently not supported because it relies on `unxhr` which does not work in VS Code (https://github.com/ggrossetie/unxhr/issues/98). +==== === Use Asciidoctor.js extensions @@ -162,9 +174,15 @@ The first time, you will also need to confirm that you trust the authors of the image::images/asciidoctor-vscode-trust-exts.png[Asciidoctor.js extensions trust confirmation message] -*❗ Important:* This feature will execute JavaScript code and should not be enabled if you don't fully trust the authors of the Asciidoctor.js extensions. +[IMPORTANT] +==== +*Important*: This feature will execute JavaScript code and should not be enabled if you don't fully trust the authors of the Asciidoctor.js extensions. +==== -*💡 Tip:* You can always update the trust mode using the command "Manage Asciidoctor.js Extensions Trust Mode". +[TIP] +==== +*Tip*: You can always update the trust mode using the command "Manage Asciidoctor.js Extensions Trust Mode". +==== You can create a new extension by creating a JavaScript file in the `.asciidoctor/lib` directory or use an existing one. Here's an example of how to use the https://github.com/mogztter/asciidoctor-emoji[asciidoctor-emoji] extension: @@ -173,17 +191,17 @@ Here's an example of how to use the https://github.com/mogztter/asciidoctor-emoj + [,shell] ---- - npm i asciidoctor-emoji +npm i asciidoctor-emoji ---- . Create a file a JavaScript file in _.asciidoctor/lib_ with the following content: + [,javascript] ---- - module.exports = require('asciidoctor-emoji') +module.exports = require('asciidoctor-emoji') ---- -. Enjoy :tada: +. Enjoy 🎉 image::images/asciidoctor-vscode-emoji-ext.png[Asciidoctor.js Emoji extension enabled!] @@ -199,6 +217,7 @@ This extension contributes the following settings: === Preview +[cols="a,a,a"] |=== | Name | Description | Default Value @@ -257,6 +276,7 @@ This extension contributes the following settings: === PDF +[cols="a,a,a"] |=== | Name | Description | Default Value @@ -283,6 +303,7 @@ This extension contributes the following settings: === Extensions +[cols="a,a,a"] |=== | Name | Description | Default Value @@ -297,6 +318,7 @@ This extension contributes the following settings: === General +[cols="a,a,a"] |=== | Name | Description | Default Value @@ -307,6 +329,7 @@ This extension contributes the following settings: === Debug +[cols="a,a,a"] |=== | Name | Description | Default Value