Thanks for considering contributing to the ClientSim project!
We will review all pull requests and merge those that improve the project, or leave constructive feedback for contributions that needs more work or changes.
The documentation for ClientSim is written in Markdown, and the ClientSim Docs site is generated from the source docs when changes are made, typically by merging a pull request.
At the bottom of each page of the Docs site is an 'Edit this page' link. When you click on this, you will be taken to a page where you can fork the repository, make changes, and then create a Pull Request to have them reviewed by the team. If you are on the VRChat team or another special VRChat GitHub team (you would know) then you can make the change directly. If you make frequent contributions, you may be invited to join a direct-contribution team.
If you'd like to write a brand-new page, you'll need to fork the repository (or clone it if you have direct write access), and create a new branch.
Once you've checked out your new branch, you can create a new markdown page within the Docs\Source folder.
- classes: Metadata autogenerated by DocFx. Do not edit these.
- guides: Tutorial documents that explain how to do things with ClientSim, step-by-step.
- images: Images that are embedded into the documents. If you make screenshots or other helpful images, save them here and you can reference them from your docs.
- systems: Explanations of the different systems that make up ClientSim for those who want to understand it at a deeper level.
You can use any text editor to write your document. Many code editors like VSCode and Rider have plugins that help when writing Markdown.
The Markdown you write will be visible in the source on GitHub and used to generate the HTML site. While there are many 'flavors' of markdown, and many renderers support special features and even many HTML tags, we recommend you stick to CommonMark for compatibility. See below for some special considerations to make your contributions work as well as possible.
Your filename should be lowercase letters only, with dashes used in places of spaces, and shortened to three words or less. A page titled "How to Set Up OSC for Worlds in ClientSim" could be named "setup-osc-worlds.md", for example
Make sure to start your page with an h1 title like this: # My Title. This will become the display name of the page on the generated site.
Image links should start with the path /images/. This does mean that they won't preview correctly in your editor, but they will resolve once the site is built. We need to come up with a way to fix this to work during editing as well.
To link from one document to another, use relative paths, including the ".md" extension. This way, the links will work while browsing the source on GitHub, and our HTML generation process will turn these into links that work on the website as well.
If you'd like to see what your page would look like before you submit a pull request, you can use the included Build System to generate the site on your machine.
- If you don't have the .NET 6 SDK installed, you'll need to download and run the .NET 6 SDK Installer first.
- Navigate to the
Tools/Nukedirectory and runsetup.cmd. If you don't have Node and NPM installed, this will install it on its first run, and show the message "Installed Node and NPM - please run this command again to Install Docusaurus." Press any key to close the window, then runsetup.cmdagain. If you already have Node and NPM installed, this will take a little longer as it installs Docusaurus, which is used to generate the site. - With these tools installed, run
build.cmdand wait as the build systems transforms and copies files. - If the process succeeds, you'll have a copy of the site built at
Tools/Docusaurus/build. The easiest way to test it is to runserve.cmdfrom theTools/Nukedirectory. This will start the Docusaurus development server at http://localhost:3000/. Visit that address and you can see your new test site. - You can leave the
servecommand running while you make further edits - justbuildthe site after making changes and refresh the site to get the new version. - You only need to do the installation steps once per development environment - with .NET, Node, NPM and Docusaurus installed, all you need to do is edit the Docs source and run the
buildcommand to see your changes.
If you followed the steps above to preview the site, you've gotten a taste of the Nuke system that powers our docs automation. Here is what happens when you run a build:
Creates the Tools/Docusaurus/build directory if it doesn't exist, and cleans it out if it does to make sure that any files you've moved or deleted are properly synced.
Turns our generic markdown format into something that Docusaurus can understand fully by adding some metadata using a YAML format called Front Matter.
This task makes a list of all the Markdown files in Docs/Source. For each file:
- Finds the first h1 header block
# Like This, and skips the file if no header is found. - If the header is found, it takes the filename of the document, replaces any spaces with
-, and adds this as theidin the Front Matter. - Sets the
titlein the Front Matter to the text of this first h1 header. - Writes the Front Matter into the top of the text file, and saves it into
Tools/Docusaurus/docs, where Docusaurus looks for markdown files.
Finds all the image files in Docs/images and copies them to Tools/Docusaurus/static/images so Docusaurus can find them when building the site.
Runs the command npm run build in the Tools/Docusaurus directory, which builds the static site from the files that were just copied over.
The generated files are not meant to be committed to git - you can generate them locally for testing and then throw them away. When a Pull Request is approved and merged into the main branch, these same steps will be run automatically on GitHub, along with a step that copies the generated site to a special gh-pages branch, which is then served as the site you can see at https://clientsim.docs.vrchat.com.
Coming soon™