Additional tooling¶

This page covers optional tooling you can add on top of the core Zensical workflow covered in Install tooling and Start editing: Visual Studio Code extensions that connect the editor directly to GitLab or GitHub, view Git history, and check your writing; converting existing Word, PowerPoint, or PDF content into Markdown; and keeping your document's images small. You don't need any of this to write or publish your document - add whichever pieces are useful to you, and skip the rest. Each section below assumes no prior Linux or command-line experience, and spells out every step.

Installing Visual Studio Code extensions¶

An extension is a small add-on that adds extra features to Visual Studio Code. The extensions covered here let you manage GitLab or GitHub directly from the editor, view your Git history inline, and check your writing for spelling, grammar, and style issues as you type.

Installing GitLab or GitHub extensions¶

VS Code doesn't require any extensions to work with GitLab or GitHub, but installing the relevant extension can make it easier to manage your documentation without leaving the editor. Some features of these extensions include:

• Viewing issues and merge requests directly in VS Code.
• Creating and managing issues and merge requests directly in VS Code.
• Viewing and managing your GitLab or GitHub repositories directly in VS Code.
• Viewing and managing your GitLab or GitHub CI/CD pipelines directly in VS Code.

Configuring GitLab or GitHub extensions¶

Once you've installed the extension, it needs permission to access your GitLab or GitHub account. The most reliable way to do this is with a personal access token (PAT) - a long, randomly generated code that works like a password, but you can limit it to just this purpose, give it an expiry date, and revoke it at any time without changing your main account password.

1. Create a personal access token (PAT) for your account:

   • Create a Personal Access Token (PAT)

     GitLabGitHub

     1. Log in to GitLab (either gitlab.com or your organisation's self-managed instance) in a web browser.
     2. In the top-right corner, click on your profile avatar and select Edit profile.
     3. On the left-hand sidebar, select Access > Personal access tokens.
     4. Click Add new token and fill out the following details:
        • Token name: Give it a clear name (for example, VS Code Extension).
        • Expiration date: (Optional) Set an expiration date according to your team's security policy. You can click on the date and select the last date available.
     5. Under Select scopes, check the api scope.
     6. Click Create token and copy the token string.

     Warning

     Copy the token string immediately. GitLab will only show it to you once; if you refresh or leave the page, it is gone forever.

     VS Code's built-in GitHub integration normally signs you in through your browser (OAuth) rather than a token, so you usually won't need a PAT for GitHub. If you use GitHub Enterprise Server and the browser sign-in doesn't work, create a personal access token instead:

     1. Log in to GitHub (either github.com or your organisation's self-managed instance).
     2. In the top-right corner, click on your profile avatar and select Settings.

     3. On the left-hand sidebar, select Developer settings > Personal access tokens > Fine-grained tokens.

        Note

        GitHub may ask you to reauthenticate before you can proceed to the next step.

     4. Click Generate new token and fill out the following details:

        • Token name: Give it a clear name (for example, VS Code Extension).
        • Expiration date: (Optional) Set an expiration date according to your team's security policy. You can click on the date and select the last date available.
     5. Select the Repository access level for the token. Choose All repositories if you want the token to have access to all your repositories, or choose Only select repositories and specify the repositories you want to grant access to.
     6. Under Permissions, select + Add permissions and add the following:
        • Read and Write access to Contents and Pull Requests.
        • Read-only access to Metadata.
     7. Click Generate token and copy the token string.

     Warning

     Copy the token string immediately. GitHub will only show it to you once; if you refresh or leave the page, it is gone forever.

2. Configure the extension to use the token you just created:

   • Configure VS Code for Git repo access

     GitLabGitHub

     GitLab's browser sign-in (OAuth) may not work in some environments, so we'll use the personal access token (PAT) instead.

     1. Open VS Code and open the Command Palette:
        • For macOS, press Cmd+Shift+P.
        • For Windows or Linux, press Ctrl+Shift+P.
     2. Type GitLab: Authenticate and press Enter.
     3. Choose your GitLab instance:
        • Select GitLab.com if you use a public cloud instance.
        • Select Add new instance URL if you use a self-hosted instance, and type your full domain (for example, https://gitlab.yourorganisation.com).
     4. Select Enter an existing token.
     5. Paste in the personal access token (PAT) you created earlier and press Enter.

     The extension instantly validates the token. If successful, your GitLab status updates in the bottom status bar, and your GitLab sidebar panel populates with your issues and merge requests.

     The built-in GitHub Authentication provider in VS Code uses a browser sign-in (OAuth) by default.

     1. Click the Accounts icon (the profile silhouette) in the bottom-left corner of VS Code.
     2. Select Sign in with GitHub (this may appear under a Copilot or Settings Sync prompt, depending on your VS Code version).
     3. Click Allow when asked to open the external website.
     4. Your browser opens GitHub to authorize the app. Click Authorize Visual Studio Code.
     5. If the browser doesn't redirect back to VS Code: GitHub displays a page saying "If your browser does not redirect you..." alongside a blue box containing an authorization token. Copy that token.
     6. Return to VS Code. Look at the very bottom Status Bar; it says Signing in to github.com.....
     7. Click that status bar text. An input box opens at the top of your editor.
     8. Paste the token you copied from the browser page and press Enter.

     Note for GitHub Enterprise Server users

     If your company hosts its own private GitHub Enterprise Server, the browser flow won't always work out of the box. To use a PAT directly, start the sign-in prompt, click Cancel on the browser authorization pop-ups, and VS Code automatically changes its prompt to a direct text field asking you to paste your Enterprise PAT.

Installing GitLens for commit history and blame¶

GitLens is a VS Code extension that adds inline "blame" annotations - showing who last changed each line, and when - directly above your text, along with a visual commit graph and richer history browsing. It's especially useful once you're using the branches and issues workflow from Managing branches and issues.

1. Click the Extensions icon in the left-hand Activity Bar (or press Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS).
2. In the search box, type GitLens.
3. Find GitLens — Git supercharged (published by GitKraken) in the results and select Install.
4. Once installed, a small annotation appears above the line your cursor is on, showing the last commit that changed it. Hover over it for full details, or select the GitLens icon in the Activity Bar for the commit graph and history views.

Installing Code Spell Checker for lightweight spell checking¶

If Vale below feels like more setup than you need right now, Code Spell Checker is a lighter alternative (or a useful complement to it) that underlines misspelled words directly in the editor as you type, with no configuration files required.

1. Click the Extensions icon in the left-hand Activity Bar (or press Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS).
2. In the search box, type Code Spell Checker.
3. Find Code Spell Checker (published by Street Side Software) in the results and select Install.
4. Misspelled words are now underlined in the editor as you type. Right-click an underlined word for suggested corrections, or to add it to your personal dictionary if it's a term you use often (such as a project name or acronym).

Install vale to check for grammar, spelling, and style issues¶

Vale is a syntax and style checker for writing. You can use it to check your documentation for grammar, spelling, and style issues.

1. Install Vale for your operating system. Open a terminal if you don't already have one open, then follow the steps below:

   • Install Vale

     macOS Windows Linux (Ubuntu)

     brew install vale
     

     1. Open PowerShell as an administrator: press the Windows key, type PowerShell, then either press Ctrl+Shift+Enter, or right-click Windows PowerShell in the results and select Run as administrator.

     2. Use the Microsoft Windows Package Manager (winget) to install Vale:

        winget install --id errata-ai.Vale
        

     1. If you don't already have snapd installed, install it:

        sudo apt update
        sudo apt install snapd
        

     2. Once you've installed snapd, install Vale:

        sudo snap install vale
        

     See the Vale installation page for other Linux distributions.

2. Create a .vale.ini file in the top-level directory of your project (the same folder that contains zensical.toml). This file configures Vale and specifies the rules and styles used to check your documentation.

   In VS Code, right-click your project's root folder in the Explorer pane and select New File.... Name the file .vale.ini (including the leading dot), then paste in the following content as a starting point:

   StylesPath = styles
   MinAlertLevel = suggestion
   Packages = Microsoft, Readability, proselint
   
   [*.{md,rst,asciidoc,html}]
   BasedOnStyles = Vale, Microsoft, Readability, proselint
   
   Vale.Terms = YES
   Vale.Avoid = YES
   Vale.Spelling = YES
   
   Microsoft.OxfordComma = YES
   Microsoft.Passive = YES
   Microsoft.Dashes = YES
   Microsoft.Spacing = YES
   Microsoft.Wordiness = YES
   Microsoft.We = YES
   

3. Create a styles directory in the top-level directory of your project. In VS Code, right-click your project's root folder in the Explorer pane and select New Folder..., then name it styles.

   Then synchronise the styles specified in .vale.ini. Open a new terminal (or PowerShell) for this, and make sure it's actually sitting in your project's root directory first:

   cd path/to/your-project
   

   Then run:

   vale sync
   

4. Install the Vale VS Code extension so Vale's suggestions appear directly in the editor:

   1. Click the Extensions icon in the left-hand Activity Bar (or press Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS).
   2. In the search box, type Vale.
   3. Find Vale (published by Chris Chinchilla) in the results and select Install.
   4. Restart Visual Studio Code once the installation finishes.

   When you open a Markdown file in Visual Studio Code, the Vale extension automatically checks it for grammar, spelling, and style issues based on the rules and styles you configured. View the results in the Problems panel: View > Problems, or the keyboard shortcut Ctrl+Shift+M (Cmd+Shift+M on macOS).

   Vale generates a large number of suggestions, some of which aren't relevant to your documentation. You can ignore these and focus on the suggestions that are relevant to your writing style and the requirements of your documentation.

5. One of the most prominent suggestions is to change from passive voice to active voice. This is a good suggestion and recommended in business writing, but it can take time to change all instances of passive voice to active voice.

   If you need some help with this, here are a few websites that can help you understand how to change from passive voice to active voice:

   • BBC Bitesize
   • Communication for Professionals
   • University of York

   You can also change the Microsoft.Passive rule in the .vale.ini file to NO if you find it too difficult to change all instances of passive voice to active voice.

Converting existing documents to Markdown¶

If you're starting from content you've already written elsewhere - a Word report, PowerPoint slides, an Excel table, a PDF - you don't have to retype it. anydoc converts Word document conversionWord, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and PDF files into clean Markdown, close enough to what this template already expects that you can paste the result straight into a page and clean up from there.

The simplest option, needing no installation, is anydoc's own browser demo - it runs the conversion locally as WebAssembly, so your document never leaves your machine. Drag a file in, and copy the Markdown it produces.

If you'd rather convert from the command line - useful for several files, or if you want to redo the conversion after editing the original - run it with npx, which downloads the tool the first time and reuses it afterwards. You already have Node.js installed from Install the diagram and maths tooling:

npx @firecrawl/anydoc report.docx -o report.md

Replace report.docx with the file you're converting, and report.md with wherever you want the Markdown written. Leave off -o report.md to print the result to the terminal instead.

Optimising images before committing¶

When you commit screenshots and diagrams to the Git repository, the PDF build also embeds them in the generated PDF, so a handful of large, uncompressed images can noticeably slow down cloning the repository and increase the size of the published PDF. Optimising (compressing) an image before you commit it usually shrinks it considerably with no visible loss of quality.

The simplest option, needing no installation, is Squoosh - a free, browser-based image compressor from Google. Drag your screenshot into the page, choose a format and quality, and download the smaller result to use in place of the original.

If you'd rather compress images from your desktop without opening a browser each time, install a dedicated tool instead:

Where to go next¶

This is the last of the step-by-step "Start Here" chapters. Shell commands is a standalone reference you can return to any time you need a reminder of a terminal command - it isn't something you need to read in order.