(#996) (ENGTASKS-3631) Switch to Astro

[st3phhays]

Description Of Changes

This converts all of the previous files that were
being generated by Statiq into Astro framework.
Now, all documentation is written in .mdx files
which are located in the src/content folders.
The README.md has been updated to reflect all of
these changes and new processes.

Motivation and Context

A move to the Astro framework will:

• Enable faster development and build times
• Give a great development experience
• Remove the dependency of .NET and utilize already used dependencies of choco-theme (Node)
• Give an easy way to use Components inside markdown (.mdx)
• Provides equivalent and new features
• Has a large community and is open source

Testing

• I have previewed these changes using the Docker Container or another method before submitting this pull request.

There are multiple options to build the site:

1. Build it on your own computer.
2. Build it using a Docker container.

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:

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 Docker Container

There are two ways to build the site using Docker:

• Using the Visual Studio Code Dev Containers extension.
• Running the Docker container from the command line.

Using the Visual Studio Code Dev Containers Extension

Connect to the Docker Container in Visual Studio Code. This will launch Visual Studio Code and open a terminal that is running inside the Docker Container whose configuration is defined in /.devcontainer/devcontainer.json and /.devcontainer/Dockerfile.

After the Docker Container has finished setup, move to a terminal and run the following:

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.

Running the Docker Container From the Command Line

From the 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.

Change Types Made

• Minor documentation fix (typos etc.).
• Major documentation change (refactoring, reformatting or adding documentation to existing page).
• New documentation page added.
• The change I have made should have a video added, and I have raised an issue for this.
  • Issue #

Change Checklist

• Requires a change to menu structure (top or left-hand side)/
• Menu structure has been updated

Related Issue

• Support Astro Framework choco-theme#405
• Add packages and scripts to install Astro on other projects choco-astro#1
• Support Astro Framework #996
• Update GenerateDocs.ps1 to support the Astro Framework choco#3446

[st3phhays]

This is draft due to a few things:

1. The PR's for choco-theme and choco-astro will need to be merged first, packages released, and updated here.
2. Confirm automatically generated docs are correct. There are a few in questions that I've recorded to look into.
3. Looking into a iFrame component for videos in docs to go along with our <Collpase /> and <Tabs /> components.
4. Need to clean up some loose ends, possible get ESLint running here.

[st3phhays]

A reason why this might be stuck in "Expected - Waiting for status to be reported" on the checks: https://github.com/orgs/community/discussions/26698#discussioncomment-3252954

[gep13]

I have just taken this for a spin, and it looks really good!

I haven't done a side-by-side comparison of each page of the docs, but I have done a couple, and the expected changes to use new way of doing xrefs, callouts, etc. all seem to be in place. I have no reason to think that the other pages won't have the same changes, so I wasn't planning on comparing each page that we have, as there are quite a few 😄

I did notice a small issue where the iframes for videos are not showing up for me, for example on this page:

/en-us/chocolatey-gui/setup/configuration/features/show-console-output

This could be a me problem, so would be good to chat about this when you are online today.

[st3phhays]

@gep13 I've made the changes suggested and rebased on master, I think this is ready for another look!

[gep13]

LGTM!