Editing through GitHub

Note: Various formatting options available in Gitbook cannot be previewed on GitHub and most local Markdown editors. Be aware of the differences between

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.

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.

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.

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.

Last updated

Logo

© Muse Group & contributors. Contents licensed under the Creative Commons-Attribution 4.0 license.