Get started

Get started with Homebrewery for VS Code

In this tutorial, you learn about the key features of Visual Studio Code (VS Code) and the Homebrewery for VS Code Extension to help you get started quickly with homebrewing. You learn about the user interface and explore how to enhance your setup with extensions and settings.

Introduction

Homebrews are custom, fan-made content for Tabletop Role-Playing Games (TTRPG, such as Dungeons & Dragons) — monsters, spells, magic items, subclasses, and full adventures — created by players and Dungeon Masters and shared with the community. What sets homebrew apart from a plain rules document is presentation: good homebrew is styled to look and feel like an official sourcebook, with the same layout, typography, and visual polish.

NaturalCrit's Homebrewery is the tool that popularized this style of content creation. It's a free, web-based editor that takes Markdown text and renders it into HTML styled to match official 5e books, which can then be exported to PDF. It has become the de facto standard for the homebrew community, but as a browser-only tool it requires writers to work outside their usual editing environment, without the benefits of local file management, version control, or editor extensions.

Visual Studio Code is a free, open-source code editor built by Microsoft, widely used across software development for its speed, built-in Git integration, and rich extension ecosystem. Its Extension API lets developers add entirely new capabilities to the editor — custom previews, language support, integrations with external services, and more — all without leaving VS Code.

Homebrewery4VSC brings the Homebrewery authoring experience directly into Visual Studio Code. It renders Homebrewery-flavored Markdown into a live, styled preview inside the editor, so homebrew creators can write and see their sourcebook-style pages update in real time, alongside the tools they already rely on: local files, Git version control, and VS Code's broader extension ecosystem. Beyond matching the core Homebrewery rendering, it adds features suited to a full authoring workflow — interactive components (dice rollers, random tables, condition trackers), file transclusion for splitting large documents across files, an SRD content browser for quick reference, and a path toward publishing finished sourcebooks directly to the web.

Install Visual Studio Code

First, you must Download and install Visual Studio Code on your computer.

Open a folder in VS Code

You can use VS Code to work on locally individual files to make quick edits, or you can open a folder, also known as a workspace.

Let's start by creating a folder and opening it in VS Code. You'll use this folder throughout this tutorial.

1. Open Visual Studio Code and select File > Open Folder... from the menu to open a folder.

2. Select New Folder and create a new folder named homebrews. Then select Select Folder (Open on macOS) to open the folder in VS Code.

   VS Code now considers the folder you've opened a workspace.

3. On the Workspace Trust dialog, select Yes, I trust the authors to enable all features in the workspace.

4. You should now see the Explorer view on the left, showing the name of the folder.

You'll use the Explorer view to view and manage the files and folders in your workspace.

Tip

When you open a folder in VS Code, VS Code can restore the UI state for that folder, such as the open files, the active view, and the layout of the editor. You can also configure settings that only apply to that folder, or define debug configurations.

Explore the user interface

Let's take a quick tour of the user interface.

Switch between views with the Activity Bar

1. Use the Activity Bar to switch between different views.

Tip

Hover over the Activity Bar to see the name of each view and the corresponding keyboard shortcut. You can toggle a view open and closed by selecting the view again or pressing the keyboard shortcut.

2. When you select a view in the Activity Bar, the Primary Side Bar opens to show view-specific information.

   For example, the Search view enables you to search and replace text in files.

Tip

For Homebrewing, you mainly use the Explorer and Search views, and optionally the Source Control view. You also use the Extensions view to install extensions.

View and edit files with the Editor

1. Select the Explorer view in the Activity Bar, and select the New File... button to create a new file in your workspace.

   

2. Enter the name mybrew.md and press Enter.

   A file is added to your workspace and an Editor opens in the main area of the window.

3. Start typing some markdown in the mybrew.md file.

   

4. Add a second files name another-brew.md to your workspace and notice that this new file opens a new Editor tab.

   You can open as many editors as you like and view them side by side vertically or horizontally. Learn more about VS Code side by side editing.

   

Access commands with the Command Palette

1. Open the Command Palette by pressing Ctrl + Shirt + P (Windows/Linux) Shift + Command + P (Mac). You can also use the View > Command Palette menu item.

   Many of the commands in VS Code are available through the Command Palette. When you install extensions, they can add extra commands to the Command Palette.

   

   [!TIP] Notice that the Command Palette shows the default keyboard shortcut for commands that have one. You can use the keyboard shortcut to run the command directly.

2. The Command Palette supports different modes of operation:

   1. Command mode (>): after the > symbol, start typing to filter the command list.

   2. Quick Open mode: remove the > character and start typing to search for files in your workspace.

   3. Symbol search mode (#): replace the > character by # to search for symbols like variables or functions in your code.

Tip

VS Code uses fuzzy matching to find files or commands. For example, typing odks returns the Open Default Keyboard Shortcuts command.

Install the Homebrewery for VS Code Extension

VS Code has a rich ecosystem of extensions that let you add languages, debuggers, and tools to your installation to support your development workflow. There are thousands of extensions available in the Visual Studio Marketplace.

Let's install the Homebrewery extension.

1. Select the Extensions view in the Activity Bar.

   The Extensions view enables you to browse and install extensions from within VS Code.

2. Enter Homebrewery in the Extension view search box. Select the Homebrewery for VS Code extension published by Iffrit Studio, and then select the Install button.

   

   After the installation completes, you should see a new view named Homebrewery for VS Code

   

3. Return to the Explorer view, open the mybrew.md file, right-click in the editor, and select Homebrewery: Open Preview to the Side.

   A preview opens for your brew. When you make changes the markdown file, the preview automatically refreshes to show the latest version.

   

Configure VS Code settings

You can customize almost every part of VS Code by configuring settings. You can use the Settings Editor to modify the settings in VS Code or directly modify the settings.json file.

1. Press CTRL + , (Windows/Linux) or Command + , (Mac) to open the Settings Editor (or select the File > Preferences > Settings menu item).

   [!TIP] Use the search box to filter the list of settings that are shown.

   

2. By default, VS Code doesn't automatically save modified files. Select a value for the Auto Save setting to change this behavior.

   

   VS Code automatically applies changes to settings. When you modify a file in your workspace, it should now be automatically saved.

3. To revert a setting to its default value, select the gear icon next to the setting and select Reset Setting.

   [!TIP] You can quickly find all modified settings by typing @modified in the search box or selecting the Modified filter.

4. You can use the tabs in the Settings Editor to switch between User settings and Workspace settings.

   User settings apply across all your workspaces. Workspace settings only apply to the current workspace. Workspace settings override user settings. Get more information about settings in VS Code.

Next steps

Congratulations! You've completed the tutorial and explored some of the key features of Visual Studio Code and the Homebrewery extension. Now that you've learned the basics of Visual Studio Code, get more info about how to:

• Edit Homebrewery's Markdown
• Organize your Brew Project
• Work with Source Control