chocolatey / docs

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. Images All images are located under the folder in the Chocolatey Image repository along with the following information: • How to add images to the image repository. • Where to find stock images. • Using images in source code. Building the Site for Development 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. Build the Site On Your Computer Ensure that you have Node v20+ installed by running . There is a 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: This will compile the site, and bring up a preview on . 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: • 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 . • 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 command from the Command Palette. Build the Site Using Docker From a terminal, run the following: Once this is complete, run the following from the same terminal: Or on Windows run: This will compile the site, and bring up a preview on . 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: Once this is complete, run the following from the same terminal: 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 , try removing the directory and clearing your yarn cache with . If you receive the error then you can increase the number by running . 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 @chocolatey-software/astro contain information on how to understand several Astro concepts. Markdown Diagrams with Mermaid Mermaid allows an easy way to display information with diagrams written in markdown. Find more information on usage at the chocolatey-software/astro repository. Adding A New Highlight 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. Front Page 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 set to . • Navigate to then into the current year folder. • Copy an existing file. • Change the name of the new file to include the month number as the first characters in the name, such as . • Fill in details needed and follow the current naming convention for xrefs in the file. • Change the value to something unique. Left Sidebar Highlight 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: • Navigate to . • Find the highlight you want to edit: for the top one, and for the bottom one. • Edit th…