Skip to content

docs: Update documentation for v0.6.0 features #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
promptless wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Update documentation for v0.6.0 features #48

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 97 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,116 +1,101 @@
# vscode-pandoc

The vscode-pandoc [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vscode-pandoc) extension lets you render markdown files as a PDF, word document, or html file.
The vscode-pandoc [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=chrischinchilla.vscode-pandoc) extension lets you render markdown files as a PDF, word document, or HTML file.

_Thanks to the previous work of [@dfinke](https://github.com/dfinke) on this extension._
> Thanks to the previous work of [@dfinke](https://github.com/dfinke) on this extension.

## Prerequisites

You need to [**install Pandoc**](http://pandoc.org/installing.html) - a universal document converter.

Alternatively you may set the `useDocker` option to true and the extension runs Pandoc in a container using the latest official [pandoc/latex](https://hub.docker.com/r/pandoc/latex) image. This could result in a delay the first time it runs, or after an update to the container while it pulls down the new image.
By default, Pandoc creates PDFs using [LaTeX](https://www.latex-project.org). If you want to use the extension for rendering PDFs, you also need to install a PDF engine. Recommendations are:

- macOS: [BasicTeX](https://www.tug.org/mactex/morepackages.html)
- Windows: [MiKTeX](https://miktex.org)
- Linux: [TeX Live](https://www.tug.org/texlive/)

## Usage

Two ways to run the extension. You need to have a markdown file open.
Pandoc can convert many different file formats to another, but not all work to and from each other. For example, most relevant to this extension, Pandoc can convert from Markdown to most other formats, but can only convert **to** AsciiDoc. [Read the full list](https://pandoc.org) for more details on supported conversion formats.

1. press `F1` on Windows (`shift+cmd+P` on Mac), type `pandoc`, press `Enter`
1. Or - press the key commination `ctrl+K` then `P` (`cmd+K` then `P` on Mac)
There are two ways to run the extension. You need to have a supported file open.

Choose from the list what document type you want to render and press `enter` (you can also type in the box rather than cursor around).
1. Press _F1_ on Windows or _shift+cmd+P_ on Mac, type "pandoc", press _Enter_.
2. Press the key combination _ctrl+K_ then _P_ or _cmd+K_ then _P_ on Mac.

## Releases
Choose from the list the document type you want to render and hit _enter_ (you can also type in the box rather than cursor around).

* December 1st, 2023
* Added pandoc.docker.options and pandoc.docker.image configurations
* Existing pandoc.useDocker configuration will be migrated to new configuration
* June 21st, 2023
* Package updates
* Read me updates
* Remove noisy console messages
* Add Docker support
* May 10th, 2023
* Package updates
* Added build workflows
* Read me updates
* October 6th, 2020
* Add ability to specify pandoc binary thanks @feeper
* Stops rendered document opening automatically thanks @bno93
* April 22nd, 2020
* Shift to new fork
* Expose further conversion options
* July 9, 2016
* Update package.json and launch.json
* Add PR #11
* Add output of the error (use OutputChannel and showErrorMessage)
* January 17, 2016
* Set pandoc options for document types
* January 16, 2016
* Handling of the path that contains spaces
* Add the open command (xdg-open) in linux

## Setting additional pandoc options

Find `pandoc` in _settings.json_ and add the options you want to use. For example:

example:
## Settings

```json
//-------- Pandoc Option Configuration --------
Override these options in the Pandoc extension settings section, or find `pandoc` in _settings.json_ and set the options.

### Override the default executable

Override this in the Pandoc extension settings section, or find `pandoc` in _settings.json_ and set the options.

// pandoc .pdf output option template that you would like to use
"pandoc.pdfOptString": "",
- Executable / `pandoc.executable`: Path to the Pandoc executable.

// pandoc .docx output option template that you would like to use
"pandoc.docxOptString": "",
- Default: Gets the path from the system's PATH variable.

// pandoc .html output option template that you would like to use
"pandoc.htmlOptString": "",
### Set the default output format

// path to the pandoc executable. By default gets from PATH variable
"pandoc.executable": "",
To set a default export format and bypass the format list prompt, set the `pandoc.defaultFormat` option in the settings.

// enable running pandoc in a docker container
"pandoc.docker.enabled": "true",
### Set Keybindings to formats

// specify the docker options when "pandoc.docker.enabled" is "true"
"pandoc.docker.options": "",
You can set keybindings to specific formats in a _keybindings.json_ file. For example, to set a keybinding for exporting to PDF, add:

// specify the docker image when "pandoc.docker.enabled" is "true"
"pandoc.docker.image": ""
```json
{
"key": "ctrl+alt+p",
"command": "pandoc.export",
"args": { "format": "pdf" }
}
```

You can set options for each output format.
Setting these skips the format selection prompt and directly exports to the specified format, but you can still use the default render command to choose a format from the list.

### Additional Pandoc command line options

Set additional command line options for each output format.

> default: `$ pandoc inFile.md -o outFile.{pdf|word|html}`

For example, for Japanese documents.
- PDF Opt String / `pandoc.pdfOptString`: PDF output additional command line options to use.
- DOCX Opt String / `pandoc.docxOptString`: DOCX document output additional command line options to use.
- HTML Opt String / `pandoc.htmlOptString`: HTML output additional command line options to use.
- AsciiDoc Opt String / `pandoc.asciidocOptString`: AsciiDoc output additional command line options to use.
- DocBook Opt String / `pandoc.docbookOptString`: DocBook output additional command line options to use.
- EPUB Opt String / `pandoc.epubOptString`: EPUB output additional command line options to use.
- RST Opt String / `pandoc.rstOptString`: RST output additional command line options to use.

Below are example options you can set for each output format.

* PDF
For example to create a Japanese PDF:

`"pandoc.pdfOptString": "--pdf-engine=lualatex -V documentclass=ltjarticle -V geometry:a4paper -V geometry:margin=2.5cm -V geometry:nohead",`
`pandoc.pdfOptString`: "--pdf-engine=lualatex -V documentclass=ltjarticle -V geometry:a4paper -V geometry:margin=2.5cm -V geometry:nohead"

* `--pdf-engine=lualatex`: need to create a Japanese PDF
* `-V documentclass=ltjarticle`: need to create a Japanese PDF
* `-V geometry:a4paper -V geometry:margin=2.5cm -V geometry:nohead"`: geometory options
To create an HTML5 document:

* Word(docx)
`pandoc.htmlOptString`: "-s -t html5"

`pandoc.docxOptString": "",`
* It will work even if you do not set the options.
> For more information, read the [Pandoc User's Guide](http://pandoc.org/README.html).

* HTML5
## Docker Options

`"pandoc.htmlOptString": "-s -t html5"`
Set the `pandoc.docker.enabled` option to `true` and the extension runs Pandoc in a container using the latest official [pandoc/latex](https://hub.docker.com/r/pandoc/latex) image. This could result in a delay the first time it runs, or after an update to the container while it pulls down the new image.

* `-s`: produce a standalone document
* `-t html5`: HTML5 output format
- Docker: Enabled / `pandoc.docker.enabled`: Enable running Pandoc in a Docker container.

For more information please refer to the [Pandoc User's Guide](http://pandoc.org/README.html).
- Default: `false`

## Docker Options
- Docker: Image / `pandoc.docker.image`: Specify the Docker image to use when running Pandoc in a container.

- Default: "pandoc/latex:latest"

When running on linux systems (and possibly others) when using the docker, there may be file permission issues with the docker image. This can appear as an error such as the following:
- Docker: Options / `pandoc.docker.options`: Additional options to pass to the Docker command when running Pandoc in a container.

When using Docker, there may be file permission issues with the docker image. For example:

```
stderr: pandoc: file.html: openFile: permission denied (Permission denied)
Expand All @@ -119,11 +104,44 @@ exec error: Error: Command failed: docker run --rm -v "/home/user/path:/data" p
pandoc: file.html: openFile: permission denied (Permission denied)
```

This may occur due to the file/directory permissions being incorrect. To allow this to function, you can specify the docker options to set the uid/gid using the following:
This may occur due to incorrect file/directory permissions. To fix, set the Docker uid/gid using the following:

```json
"pandoc.docker.options": "--user $(id -u):$(id -g)"
```
`pandoc.docker.options`: "--user $(id -u):$(id -g)"

If needed, you can also change the default Pandoc docker image using the `pandoc.docker.image` configuration setting.

## Releases

If needed, you can also change the default pandoc docker image using the `pandoc.docker.image` configuration setting.
- June 25th, 2025
- Add option to specify a default export format
- Add option to use keybindings to export to specific formats
- Readme and settings overhaul
- Dependency updates
- December 1st, 2023
- Added pandoc.docker.options and pandoc.docker.image configurations
- Existing pandoc.useDocker configuration will be migrated to new configuration
- June 21st, 2023
- Package updates
- Read me updates
- Remove noisy console messages
- Add Docker support
- May 10th, 2023
- Package updates
- Added build workflows
- Read me updates
- October 6th, 2020
- Add ability to specify pandoc binary thanks @feeper
- Stops rendered document opening automatically thanks @bno93
- April 22nd, 2020
- Shift to new fork
- Expose further conversion options
- July 9, 2016
- Update package.json and launch.json
- Add PR #11
- Add output of the error (use OutputChannel and showErrorMessage)
- January 17, 2016
- Set pandoc options for document types
- January 16, 2016
- Handling of the path that contains spaces
- Add the open command (xdg-open) in linux

Loading