Additional tooling¶

The installation route you chose provides everything needed to write, build, and publish a document. This page contains optional tools that may make particular authoring tasks easier. Choose only the sections that match your work; none is required before you continue with the guide.

Choose what you need¶

Work with GitLab or GitHub in Visual Studio Code¶

Visual Studio Code can commit, pull, and push with Git without either extension. Use the SSH connection configured by the installation route for those Git operations. Install one of these extensions only if you also want to view issues, review changes, or inspect pipelines without leaving the editor.

Connect the extension to the repository service¶

SSH remains the preferred connection for cloning, pulling, and pushing. The extension needs a second, separate account connection because issues, reviews, and pipeline information come from the GitLab or GitHub web API rather than from Git. This account connection does not replace or reconfigure SSH.

Help with repository sign-in¶

• If GitLab rejects a token, check that it has not expired, that it includes the api scope, and that you selected the correct GitLab address.
• If browser sign-in does not return to Visual Studio Code, copy the code shown by the browser and use the sign-in message in the editor's status bar.
• If an old account keeps appearing, sign out from the Accounts menu in Visual Studio Code, then authenticate again.
• If Git works in a terminal but the extension does not, do not replace a working SSH key. Git access and extension sign-in are separate connections; authenticate the extension again instead.

Inspect Git history with GitLens¶

GitLens (website) adds more detailed history views to Visual Studio Code. It can show the commit that last changed a line and provide a visual commit graph.

1. Open Extensions in Visual Studio Code.
2. Search for GitLens.
3. Select GitLens — Git supercharged published by GitKraken, then select Install.
4. Open a tracked file and place the cursor on a line to see its most recent change. Open the GitLens view from the Activity Bar for the wider history.

Use this when the built-in Source Control history is not detailed enough. Some GitLens features may require an account or paid plan; the extension shows which features are available before you use them.

Check spelling and writing style¶

Choose the smallest tool that meets the project's needs.

Add lightweight spelling checks¶

Code Spell Checker underlines words that are not in its dictionary. It requires little setup and is useful for an individual author.

1. Open Extensions in Visual Studio Code.
2. Search for Code Spell Checker.
3. Select Code Spell Checker published by Street Side Software, then select Install.
4. Right-click an underlined word to correct it or add a genuine project term to a dictionary.

Add shared checks with Vale¶

Vale (website) applies writing rules stored with the project. Choose it when a team needs the same checks on every computer or in an automated pipeline.

1. Install Vale for the operating system.

   macOS Windows Linux (Ubuntu)

   If Homebrew is not installed, use its official installer. Follow every post-install instruction it prints so that brew is added to your shell.

   Install Homebrew

   After Homebrew finishes installing, close Terminal completely and reopen it. The current terminal will not know about the new brew command.

   In the reopened terminal, check that Homebrew is available, then install Vale:

   brew --version
   brew install vale
   

   Open PowerShell, then run:

   winget install --id errata-ai.Vale
   

   sudo snap install vale
   

   If Snap is not installed, follow Vale's Linux installation choices instead of adding a new package manager only for this tool.

2. In the top-level project directory, create .vale.ini with an initial configuration:

   StylesPath = styles
   MinAlertLevel = suggestion
   Packages = Microsoft, Readability, proselint
   
   [*.{md,rst,asciidoc,html}]
   BasedOnStyles = Vale, Microsoft, Readability, proselint
   

3. Open a terminal in the same directory and download the selected rule sets:

   vale sync
   

4. Check the Markdown files:

   vale docs
   

5. To see results while typing, install the Vale extension published by Chris Chinchilla in Visual Studio Code, then restart the editor.

Treat Vale's results as advice. Agree the rules with the people reviewing the document before spending time correcting every suggestion.

Convert an existing document to Markdown¶

anydoc (repository) can convert Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and PDF files into Markdown. The result is a starting point, not a finished page.

The simplest route is the anydoc browser tool. The conversion runs in the browser, and its interface states that the selected file does not leave the computer.

To convert several files from a terminal, use npx after installing Node.js:

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

Replace the two filenames with the source and destination. Compare the result with the original, paying particular attention to tables, footnotes, images, and complex layouts before moving it into docs/.

Optimise images before committing¶

Optimisation keeps large screenshots from making a repository slower to clone or increasing the PDF size. Keep an original outside the repository, optimise a copy, and check that text and important details remain legible before committing it.

The simplest option is Squoosh, which runs in a browser. For regular use, install a desktop or command-line tool:

brew --version
brew install --cask imageoptim

sudo apt update
sudo apt install pngquant jpegoptim

pngquant --ext .png --force example.png
jpegoptim example.jpg

Where to go next¶

Optional tooling is now complete. Continue to Start editing to open the project, preview the website, build the PDF, and save changes with Git. Return to this page later if a new authoring need appears.