Chocolatey Docs

This repository contains the source files for the documentation site that can be found here:

https://docs.chocolatey.org/en-us/

This site is built using Astro.

Writing Documentation

Listed below are some of the areas we consider important when writing. We have two goals:

• Consistency. It's important when writing to be consistent in all areas including, but not limited to, headings, code style, formatting, use of bold and italics. We acknowledge that as our writing style has evolved not all of our writing has followed. When we write we should be consistent.
• Clarity. When writing we must remember to write for others and not just for ourselves. It's important to understand that jargon or acronyms can cause confusion, misunderstanding and a barrier for others who are not familiar with the terms. Avoid using jargon where you can and only use acronyms once they have been defined. Ensure any jargon or acronyms used are documented.

To help with these goals, please refer to our guides on writing documentation and the use of language and grammar.

Building the Site for Development

There are multiple options to build the site:

1. Build it on your own computer.
2. Open in GitHub Codespaces.
3. Build it using a Dev Container.
4. Build it using Docker.

Build the Site On Your Computer

Ensure that you have Node v20+ installed by running node -v. There is a .\setup.ps1 file in the root of this repository that uses Chocolatey to install or upgrade Node to the correct version.

After confirming the required Node version, run the following command from a terminal:

yarn dev

This will compile the site, and bring up a preview on http:localhost:5086. Any changes you make will automatically be hot reloaded.

Build the Site Using a Dev Container

Follow these steps to open the project in a Dev Container:

1. Install the Dev Containers extension for Visual Studio Code if you haven't already. You can install it from the Extensions view (Ctrl+Shift+X) by searching for "Dev Containers".
2. Open the Command Palette (Ctrl+Shift+P or F1) and run the command Dev Containers: Open Folder in Container....
3. Select the folder containing this repository (or the repository root if you've already opened it in VS Code).
4. Wait for the Dev Container to start up. This may take a few minutes the first time as it needs to download the container image. Subsequent starts will be faster.
5. Once the Dev Container is ready, you'll have a full development environment with all the required tools and dependencies pre-installed. Any changes you make will automatically be hot reloaded.
6. When you're done, you can close the Dev Container by running the Dev Containers: Close Remote Connection command from the Command Palette.

Build the Site Using Docker

From a terminal, run the following:

docker build -t chocolatey-docs-container .

Once this is complete, run the following from the same terminal:

docker run -p 5086:5086 -v $(pwd):/app chocolatey-docs-container

This will compile the site, and bring up a preview on http:localhost:5086. Any changes you make will automatically be hot reloaded.

Building the Site for Production

Building the site for production is a good practice before submitting a pull request. An error of any kind will be flagged in the production build and it will fail.

From a terminal, run the following:

yarn build

Once this is complete, run the following from the same terminal:

yarn preview

This will start a server to show what the site will look like in production. Changes made to source files will not be reflected in this preview.

Troubleshooting the Build

If you are having build errors with 'copyTheme' errored after, try removing the node_modules directory and clearing your yarn cache with yarn cache clean.

If you receive the error The configured user limit (128) on the number of inotify instances has been reached, or the per-process limit on the number of open file descriptors has been reached then you can increase the number by running echo fs.inotify.max_user_instances=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p. See this GitHub comment for more information.

Recommended VS Code Extensions

The following VS Code extensions are recommended to get the best development experience:

• Astro - Syntax highlighting for .astro files.
• MDX - Syntax highlighting for .mdx files.
• JavaScript and TypeScript Nightly - JavaScript and TypeScript intelliSense.
• ESLint - Highlights syntax errors in .ts and .js files.
• markdownlint - Highlights syntax errors in .md and .mdx files.
• Trailing Spaces - Highlights trailing spaces and allows you to easily delete them.
• Code Spell Checker - Highlights spelling errors and suggests fixes.
• Gremlins - Highlights characters that can be harmful because they are invisible or look like legitimate ones.

Understanding Astro

The Chocolatey Design System and choco-astro contain information on how to understand several Astro concepts:

• Learn how to override automatically generated heading ID's.
• Learn about Astro and how to use Components in .mdx and .astro file types.
• Learn how to use the <Callout /> Component to display notes and important information.
• Learn how to use the <CollapseButton /> Component to display a button that triggers a collapsed element.
• Learn how to use the <Iframe /> Component to display videos with defined aspect ratios.
• Learn how to use the <Tabs /> Component to display content in tabbed interface.
• Learn how to use the <Xref /> Component to link to other documents within this repository.

Markdown Diagrams with Mermaid

Mermaid via an Astro integration allows an easy way to display information with diagrams written in markdown. Find more information on usage at the choco-astro repository.

Running Playwright Tests

To run all the Playwright tests, first run the following command:

yarn build

Once this has completed, run:

yarn playwright

This will run all Playwright tests and report any errors for further investigation.

Build Status

Chat Room

Come join in the conversation about Chocolatey in our Community Chat Room.

Please make sure you've read over and agree with the etiquette regarding communication.

Search

Search uses Algolia DocSearch as backend.