Homebrewery for VS Code
Edit your favorite TTRPG content in your favorite editor.
This VS Code extension provides an editor for your TTRPG content (aka Brews) using Markdown syntax supported by The Homebrewery.
It provides completion snippets and a built-in live preview.
It is inspired by some projects listed in related projects.
Installation
This extension requires Visual Studio Code. Once VSCode is installed, search for the extension or install it from here.
Features
This extension provides the following features:
- Extended Markdown editor to generate beautiful documents in the style of the Dungeons & Dragons books and resources.
- Snippets for the Homebrewery syntax.
- Live Preview with synchronized scrolling.
- Generate HTML for PDF printing.
Editor
This extension enhances the default Markdown editor with:
- Completion snippets.
- Coloring for
metadata and css fenced code blocs.
- Toolbar button named Homebrewery: Open Preview to the Side, with an alternate Homebrewery: Open Preview button.
Snippets
Snippets provide access to the extended Markdown syntax implemented by Homebrewery. They can be accessed with CTRL+Space in Markdown documents.
Homebrewery snippets start with Homebrewery.
Font icons provided in Homebrewery are also available as snippets. These start with Font Icon.
NOTE: As these snippets can clutter the completion dropdown, you can disable them with the homebrewery4vsc.enableFontIconCompletions setting.
Commands
From a markdown editor:
- Homebrewery: Open Preview opens a live preview.
- Homebrewery: Open Preview to the Side opens a preview to the side of the current editor.
- Homebrewery: Generate HTML generates a plain HTML file named after the brew file. This file can be viewed and printed as PDF from a web browser.
From the preview:
- Homebrewery: Change Layout to ... switches the layout to single page, two pages and flow.
- Homebrewery: Change Zoom In/Out Preview zooms the preview.
- Homebrewery: Reset Preview Zoom resets the zoom.
Preview and HTML Output
The live preview displays your markdown document as a Homebrewery rendering, with multiple page.
The Preview toolbar includes buttons to switch the layout and zoom in the preview.
Note that the preview automatically scrolls with the editor position. To scroll the editor to a specific page, click that page in the preview.
You can configure the preview behavior and HTML output in the extension settings.
Themes
The extension includes the 5e Player's Handbook , 5e Dungeon Master's Guide, and Journal default themes from the Homebrewery.
Each brew can use a different theme, indicated in the theme property of the metadata fenced block within the brew file.
If no theme is declared in the brew, the default theme configured in the homebrewery4vsc.theme setting applies.
Example: A brew using the 5ePHB (5e Player's Handbook) default theme.
```metadata
title: The Vampire's Bride
description: 'Test to use a well known style.'
tags:
- meta:Scenario
systems:
- 5e
renderer: V3
theme: 5ePHB
```
The story starts here.
...
You can refer in the theme property to another brew from your workspace and use it as a local theme.
This brew file should have:
- A
theme property of the metadata fenced block, pointing to one of the default themes.
- A
css fenced block containing the various styles that compose this theme.
Example: A brew referring to a HB-StrahdStyle.txt theme in the workspace.
```metadata
title: The Vampire's Bride
description: 'Test to use a well known style.'
tags:
- meta:Scenario
systems:
- 5e
renderer: V3
theme: ./themes/HB-StrahdStyle.txt
```
The story starts here.
...
The content of the HB-StrahdStyle.txtfile. It uses the 5ePHB base theme, and adds CSS on top of it.
```metadata
title: Strahd Style
description: 'This is a theme file'
tags:
- meta:Theme
systems:
- 5e
renderer: V3
theme: 5ePHB
```
```css
/* A lot of CSS here */
TIP: A large set of awesome templates (designed by @KaiburrKathHound) are available from The Homebrewery
CSS
In addition to the themes, the extension supports a cssfenced block in a brew to define local styles.
You can also set in the homebrewery4vsc.customStyleSheets setting a list of css files that will apply to all your brews in the workspace.
Extension Settings
This extension exposes the following settings:
homebrewery4vsc.enableFontIconCompletions: Enable/disable the font icon completion snippers.homebrewery4vsc.highlightColumnAndPageBreaks: Highlight entire lines containing page and column breaks, for better editor readability.homebrewery4vsc.scrollPreviewWithEditor: Enable/disable preview scrolling with the editor.homebrewery4vsc.theme: The theme (Player's Hanbook, Dungeon Master's Guide, etc) used in preview and the HTML output.homebrewery4vsc.customStyleSheets: List of style sheets (CSS files within the workspace or accessed with HTTP) added to all documents when rendering.homebrewery4vsc.pageFormat: Preview and HTML output page format (A4 or Letter).homebrewery4vsc.inlineLocalImages: Inline local images in the HTML output. This creates standalone HTML files.homebrewery4vsc.hideBackground: Hide the background image and color in the preview or the HTML output, mainly for printing.
Credits
This extension is inspired from the Dungeon and Markdown extension by Spjak Software (Jacob Olesen).
This extension uses the Themes, Icons and Markdown Renderer from The Homebrewery, under the MIT license.
The Homebrewery is copyright (c) 2016 Scott Tolksdorf.
Many thanks to the contributors who keep this project alive!
FAQ
VS Code comes with a default markdown preview, which adds to the markdown editor's toolbar a button labelled Open Preview to the Side. To hide it from the toolbar, right-click the button and select Hide 'Open Preview to the Side', as shown below. You can restore it later if needed.
How to synchronize my workspace with the Homebrewery?
The Homebrewery provides a feature to synchronize your brews in your Google Drive Folder. For automated synchronization:
- Create your brews in the Homebrewery, and activate the Google Drive synchronization there.
- Add the Google Drive > My Drive > Homebrewery folder to the VS Code workspace.
- Edit the brew files generated in this folder by the Homebrewery.
Changes done in VS Code will appear in the Homebrewery and vice-versa.
How to work with text (.txt) files?
When editing brews in the Homebrewery, or downloading sources, you'll notice that these files have a .txt extension (and not .md).
VS Code recognize these files as markdown but as Plain Text. To have them associated to the Markdown syntax:
In the VS Code status bar (at the bottom of the window), click Plain Text.
In Select Language Mode, select Configure File Association for .txt...
Finally, select Markdown .
Known Issues
