Boost Quickbook Support Extension
From the Boost.Quickbook website:
QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks.
This Visual Studio Code extension provide some simple language support to ease the task of authoring Boost.Quickbook(source) files.
It is not endorsed, published, approved or peer-reviewed by the Boost community,
or anybody represented by the community. I have simply written it for myself to use - and put it out in the ether in case somebody else may find it useful too.
It is called "Boost Quickbook Support" because Quickbook is a Boost-published language/tool,
and when I google "Quickbook" on its own, the search engine assumes I mean accounting software.
For the preview feature to work, you need a
quickbook executable - either accessible within your
or explicitly specified in the
The executable's command options (see
quickbook --help) when generating the preview,
are represented by equivalent settings.
Consult the Quickbook documentation for appropriate usage.
File System Paths
All filesystem path settings (i.e. to be passed as command-line options to
quickbook, when generating the preview),
can be specified relative to the VSCode workspace directories;
These settings are processed as follows:
- The specified path is quoted and tested as is - if it exists, it is used.
- Otherwise the specified path is pre-pended in turn by each of the workspace directories - if it exists, it is used.
- Otherwise the specified path is quoted and used as specified.
Local Images with a relative path
By default, the extension's preview will temporarily adjust local relative image URI's
[$ ...] directives with a relative path),
by rooting image paths to the directory of the source Quickbook file (i.e. the file that is being previewed).
This can be prevented by setting the Security: Process Image Relative
quickbook.preview.security.processImagePathRelative) setting to false.
Also see Security below for more on these, and related settings.
The WebView API documentation component
used to display the preview panel are very restrictive with regards to what resources can be accessed.
- Any external resources needs to be explicitly trusted with the "Content Security Policy".
- Local resources:
- Needs to be accessed with a special
- The scheme also needs to be explicitly trusted with the "Content Security Policy".
- The root directories that contain local resources, need to be explicitly trusted, by adding them to
See the WebView API documentation
for more on this subject.
This extension provides the following features to accommodate the above requirements.
Content Security Policy
quickbook generated preview HTML is injected with a
<meta http-equiv="Content-Security-Policy" content="****"> directive, where the
**** part is replaced by the contents of the Security: Content Security Policy (
This setting defaults to "
default-src vscode-resource: https:;" - thus allowing to access local (trusted),
By default, the extension's preview will temporarily adjust the scheme of all local image URI's
[$ ...] directives with a local path)
to access the image with the "
vscode-resource:" scheme, for rendering in the preview.
This can be prevented by setting the Security: Process Image Path Scheme
quickbook.preview.security.processImagePathScheme setting to false.
The following settings will add their respective directories to the trusted list (
- Security: Trust Source File Directory (
When enabled (default), the directory of the source file (i.e. the file being previewed) is trusted.
- Security: Trust Workspace Directories (
When enabled (default), all of the workspace directories are trusted.
- Security Trust Specified Directories (
When enabled (default), all other setting-directory-paths are trusted;
- Boost Root Path (
- CSS Path (
- Graphics Path (
- Image Location (
- Include Paths (
- Trusted Additional Directories (
A manually entered list of additional paths to trust.
All graphics (callouts etc.) embedded by
quickbook into the preview html will be implicitly post-processed
to be accessed with the
This will still require the Security Trust Specified Directories
quickbook.preview.security.trustSpecifiedDirectories) setting to be enabled to work - in order to trust
the Boost Root directory.
Any stylesheet specified with the CSS Path (
quickbook.preview.CSSPath) setting will be implicitly post-processed to be accessed with the
This extension is not bullet proof. It is only intended as the next step up from a pure text editor - not as a complete documentation writing tool.
Currently it suffers from the following caveats.
See the GitHub Issues Page for more.
- Bracket & Quote matching does not recognise escaped characters:
[myTemplate includes a \] character]
does not match correctly on the last
is simply specified inside the
I don't know how to do specify the concept of an escaped character in there - if possible at all.
Some answers to potential problems can be found here.
The CHANGELOG will list details of what changed within each release.