Any page of both support.audacityteam.org and plugins.audacityteam.org can be edited either on Gitbook (see #writing-tutorials-and-user-guides for instructions) or using Markdown syntax on GitHub.
Note: Various formatting options available in Gitbook cannot be previewed on GitHub and most local Markdown editors. Be aware of the differences between
Gitbook-hosted pages (plugins/support.audacityteam.org)
The reverse isn't true however: All Github-flavored markdown is supported in Gitbook.
A link for GitHub is shown either on the right-hand side or in an overflow menu of any page:
Once you are on GitHub, you will see a pencil in the top right of the file.
You now can make your changes to the page.
Best Practice: Frequently switch between the Code and Preview tabs in GitHub to get a general sense of what your edit will look like.
Also, if you haven't already, now is a great time to familiarize yourself with the Style Guide.
Once you are done, press Propose Changes
This brings you to a page where you can review your changes. If you are satisfied, click Create Pull Request.
After you click "create pull request", it will show up on https://github.com/audacity/audacity-support/pulls and await review by an Audacity team member.
You can edit Markdown in any text editor. More advanced editors like VSCode may show useful shortcuts and visualizations for easier and faster editing, but in principle, even the simplest text editors like Windows Notepad can be used to create them.
Caution: Avoid using office suites like Microsoft Word, LibreOffice or Google Docs to edit Markdown. They tend to use very different formatting options, which don't transfer to plain text. As a rule of thumb, if it doesn't save in .txt or .md, it's not the right app to use as a Markdown editor.
To get started, first clone the repository, either using git clone https://github.com/audacity/audacity-support.git by clicking the code button on https://github.com/audacity/audacity-support and opening it in GitHub Desktop
Note: You will need to use some form of Git to make a pull request, so just downloading the ZIP will not work.
Once it's cloned, you'll find the files of support.audacityteam.org in the main branch, and the files of plugins.audacityteam.org in the plugins branch. Any additional branches have been split off from the main branch to preserve documentation for previous versions of Audacity.
Further information on using git with VScode can be found in the VSCode docs.
Outside from the syntax requirements, there are some more technical things you need to be aware of:
The sidebar menu is handled through SUMMARY.md, not the file structure itself. If you want the page you created to show up in the sidebar, you will need to update this file accordingly. That said: Try to match the structure of SUMMARY.md with the folder structure.
While you technically can work directly in your fork's main/plugins branch, it is highly recommended to make a new branch based on upstream/main or upstream/plugins instead for your changes. This way, you can always fast-forward merge the latest changes into your fork.
When updating your fork's side-branches to the latest state of main, rebase it if possible.
