Repository files navigation

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 usingAstro.

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 anyjargon or acronyms used are documented.

To help with these goals, please refer to our guides onwriting documentation and the use oflanguage and grammar.

There are multiple options to build the site:

1. Build it onyour own computer.
2. Open inGitHub Codespaces.
3. Build it using aDev Container.
4. Build it usingDocker.

Ensure that you have Node v20+ installed by runningnode -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 onhttp:localhost:5086. Any changes you make will automatically be hot reloaded.

Follow these steps to open the project in aDev 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 commandDev 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 theDev Containers: Close Remote Connection command 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-p5086:5086-v$(pwd):/app chocolatey-docs-container

This will compile the site, and bring up a preview onhttp: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 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.

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

If you receive the errorThe 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 runningecho fs.inotify.max_user_instances=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p. Seethis 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.

TheChocolatey Design System andchoco-astro contain information on how to understand several Astro concepts:

• Learn how tooverride automatically generated heading ID's.
• Learn about Astro and how to useComponents 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.

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

A Highlight is what is shown on the home page of docs.chocolatey.org and the left sidebar. These need updated every so often, especially when there has been a new release. Follow the steps below to add a new Highlight.

For front page highlights, we should try to keep it to less than 6 highlights. When adding a new one, consider editting existing highlights to setshowOnHome tofalse.

1. Navigate tosrc/content/docs/en-us/highlights then into the current year folder.
2. Copy an existing file.
3. Change the name of the new file to include the month number as the first characters in the name, such as10-testing-home.md.
4. Fill in details needed and follow the current naming convention for xrefs in the file.
   1. Change thectaText value to something unique.

For left sidebar highlights, we want to keep it to a minimum to reduce the amount the navigation is pushed down the page. It's recommended to edit only the top highlight file to link to the current highlighted article, and leave the bottom one to link to all highlights.

To edit either of these highlights:

1. Navigate tosrc/content/docs/en-us/highlights.
2. Find the highlight you want to edit:00-top-sidebar-highlight.md for the top one, and99-bottom-sidebar-highlight.md for the bottom one.
3. Edit the details as desired making note of the followinghighlight front matter settings that control the destination and link text:

   ctaXref: highlightsctaAnchor: december-2024ctaText: View December's highlights

If it's decided that extra highlights should be added:

1. Navigate tosrc/content/docs/en-us/highlights.
2. Copy one of the existing*sidebar-highlight.md files.
3. Change the name of the new file to start with a number that will determine it's order in the sidebar, such as10-testing-home-sidebar-highlight.md. Ensure the-sidebar-highlight in the name is retained.
4. In the nestedhighlight front matter, ensure the following are set in the nestedhighlight front matter:

   showOnHome: falseshowOnHighlights: falseshowInSidebar: true

5. Fill in the rest of the details needed and follow the current naming convention for xrefs in the file.
   1. Change thectaText value to something unique.
6. If there is a Sidebar Highlight already active, find the file that it is referencing. The title and post date can be a clue as to what file this is inside of thesrc/content/docs/en-us/highlights folder.
7. In the nestedhighlight front matter on the OLD file, ensure the following are set:

   showOnHome: falseshowOnHighlights: falseshowInSidebar: false

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.

Come join in the conversation about Chocolatey in ourCommunity Chat Room.

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

Search usesAlgolia DocSearch as backend.