Editing through GitHub

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)

• Github-flavored markdown renderers and

• Raw Markdown.

The reverse isn't true however: All Github-flavored markdown is supported in Gitbook.

Editing through Github.com

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.

On a technical level, this will create a "fork" of the page, found on your Github profile, with a new branch called "patch-#" in which you are editing. As long as you are within this branch, you can do whatever you want with out stepping on anyone's toes.

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

On a technical level, this creates a commit in your "patch-#" branch. A branch can hold as many commits as you like, so if you want to do multiple changes, you can exit the flow after clicking "propose changes" and edit another file instead.

This brings you to a page where you can review your changes. If you are satisfied, click Create Pull Request.

Clicking this button creates a form...

... in which you can give an overview of your changes to the team.

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.

Editing through a local editor

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.

Example of switching branches in the GitHub Desktop client

Example of switching branches in VSCode

Further information on using git with VScode can be found in the VSCode docs.

Technical notes

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.