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

Thanks

The original template that was used to create this docs site came from the work that was done by Patrik Svensson, on his Spectre.Console and Spectre.Cli docs sites. Huge thank you to Patrik for all his help!

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

Setup

There are a number or pre-requisites that are needed before you will be able to build the website locally. These include:

• .NET Core SDK
• NodeJS

There is a .\setup.ps1 file in the root of this repository that can be used to install all necessary packages, and which will be kept up to date as these change.

Building the site

To build the site locally on your machine, either run the .\build.ps1 or the build.sh file (depending on your system). This will compile the site, and all generated output file be placed into the output folder.

Previewing the site

To preview the site locally on your machine, either run the .\preview.ps1 or the preview.sh file (depending on your system). Once completed, you should be able to open a browser on your machine to http://localhost:5080 and the site will be loaded. Once running, any changes made to the files within the input folder will cause the site to be rebuilt with the new content.

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.

Adding a New Highlight

To add a new Highlight, follow the steps below:

1. Check to see if the Highlight you are writing already has a folder associated with it. This will match the current year and month that you are posting the Highlight in. If there is already a folder, copy the file from /en-us/highlights/template/template.md into the folder your new Highlight will go in, then skip to step #4.
2. Copy the folder /en-us/highlights/template and rename it to the format of "YYYY-MM". For example: "2023-04".
3. In your new folder, update the index.md file:
   1. Change the PostedDateTime to the first day of the current month. This should match the folder name. This will be the heading title that appears on the Highlights page.
   2. Remove the IsActive: false line completely. This is set to true by default, and a section will now appear for the given month on the Highlights page.
4. In your new folder, change the file name of template.md to match the title of the Highlight you are writing. This should be something that can easily be identified if changes will need to be made by another person later.
5. Update your new (previously template.md) file as needed:
   1. Remove the IsActive: false line completely. This is set to true by default, and will now be shown on the Highlights page.
   2. To make the Highlight appear on the Home page, remove the ShowOnHome: false line completely. This is set to true by default, and will now be shown on the Home page.

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. Configuration for crawler is available at https://github.com/algolia/docsearch-configs/blob/master/configs/chocolatey.json.