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.
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.
There are multiple options to build the site:
- Build it on your own computer.
- Open in GitHub Codespaces.
- Build it using a Dev Container.
- Build it using Docker.
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 devThis will compile the site, and bring up a preview on http:localhost:5086. Any changes you make will automatically be hot reloaded.
Follow these steps to open the project in a Dev Container:
- 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".
- Open the Command Palette (Ctrl+Shift+P or F1) and run the command
Dev Containers: Open Folder in Container.... - Select the folder containing this repository (or the repository root if you've already opened it in VS Code).
- 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.
- 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.
- When you're done, you can close the Dev Container by running the
Dev Containers: Close Remote Connectioncommand from the Command Palette.
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-containerThis 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 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 buildOnce this is complete, run the following from the same terminal:
yarn previewThis 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.
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.
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.
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
.mdxand.astrofile 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.
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.
To run all the Playwright tests, first run the following command:
yarn buildOnce this has completed, run:
yarn playwrightThis will run all Playwright tests and report any errors for further investigation.
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 uses Algolia DocSearch as backend.