Using GitBook
Overview
Organization
User content on GitBook is always owned by an Organization. In our case, that's MuseScore.
Space
Within an organization, you can create Spaces for different content. We currently have one space called English (US), which is for the handbook's English source text. We'll add more spaces later; one for each translation, including English (GB) if we want (or we could rename the main one "English").
Site / Docs site
To make a space viewable to the public, it must be added to a Docs site (aka 'site'). We currently have one site called MuseScore Studio Handbook. This site will be used for the source space and all translations.
When the handbook site is published, it will be available at:
https://musescore.gitbook.io/ (alias because it's the default site for this organization)
We also have the option to use a custom subdomain of our own website, such as:
While a site is published, live edits on its spaces are disabled, so all changes must be made though change requests (or on GitHub if GitHub sync is enabled).
GitHub sync
The content within a space can be synced with a GitHub repository. In the repository, content is stored as Markdown files, with subfolders for each parent page or group.
The sync is two-way, so edits made in either place will be reflected in the other. This will enable us to:
Edit the source text on GitBook or GitHub.
Upload strings from GitHub to Transifex.
Download translations from Transifex to GitHub.
Sync translations back to GitBook.
While GitHub sync is enabled, live edits are disabled, so all changes must be made though change requests, or on GitHub via pull requests or direct commits to the repository.
Navigation
Summary / Table of contents
On the left side of the screen is a list of groups, pages and subpages in the current space. This list is the summary or table of contents. If GitHub sync is enabled, the summary appears in a file called SUMMARY.md at the root of the space.
To prevent a specific page appearing in the summary, go to Page actions (⋮) > Hide page.
The page will still appear in search results and be accessible to anyone with the URL.
Page outine / On this page
On the right side of the screen, under the label "ON THIS PAGE", is a list of headings on the current page. This is the page outline. Only Heading 1 and Heading 2 headings are shown in the outline.
Heading 3 (not shown in page outline)
To hide the sidebar for the summary or page outline, go to Page actions (⋮) > Options.
The summary and page outline will remain visible on other pages.
Pages
You're viewing a page now. This page is actually a subpage of the main page. It's also possible to have subsubpages, and so on.
By default, parent pages are collapsed in the summary, so you can't see their subpages. Subpages become visible when you view the parent page or click the expansion arrow next to it in the summary.
Groups
Pages can also be nested under groups. Group names appear in BLOCK CAPITALS in the summary.
Unlike parent pages, groups are always expanded in the summary and cannot be collapsed. Also, groups cannot be nested under other groups or pages.
Groups are not pages and so cannot contain content of their own. If you try to visit a group URL, GitBook will redirect you to the first page in the group.
Editing
Live edits
GitBook has a live edit mode where you can edit content directly without creating a "branch" first. In this mode, you can add, move, rename, and delete pages, as well as edit content on existing pages.
Live edits are disabled while a site is published, or while GitHub sync is enabled.
If editing is disabled, many of the menus (⋮), options (⠿), and buttons (+) mentioned on this page will not be available until you start making a change request.
Change request (CR)
While live edits are disabled, the only way to make changes is via a change request, or ‘CR’. This creates a personal ‘branch’ on which editing is enabled. Your CR branch covers the entire space, so it’s possible to edit multiple files in a single CR if necessary, but this should only be done if the changes are related.
When you’re done editing, you can submit your CR for review, like a GitHub pull request (PR). Like PRs, change requests should always be given a meaningful title that describes the change made. Ideally, the title should be written in the imperative mood, which means it should complete the sentence “This change request will...”.
"shoogle's Nov 21 changes"
Default CR name. It's not descriptive enough.
"Metric modulations"
Bare minimum.
"Added images of metric modulations"
Better, but not in imperative mood.
"Add images of metric modulations"
This is in the imperative mode.
"Tempos: Add images of metric modulations"
In imperative mood and identifies the topic being edited.
In general, each change request should only do one thing. That thing might be:
"Add page: Rhythm"
"Rename 'Meters' page to 'Time signatures'"
"Installation on Linux: Remove unnecessary detail"
"Replace 'MuseScore 4' with 'MuseScore Studio' on all pages"
In naming your CR, if you can't avoid using the word "and" (as in "Do this and do that"), that's a clue you should consider splitting your edits across multiple CRs instead.
Resolving conflicts
While you’re waiting for your change request (CR) to be merged, the content it’s based on could change in the primary space (e.g. if someone else’s CR gets merged before yours). If this happens, GitBook will prompt you to update your change request to reflect the new primary content.
When you click the Update button in your CR, GitBook will alert you to any conflicts that it is not able to resolve automatically. This happens if you changed a block (i.e. a paragraph) that was also changed in the primary space. In this case, GitBook displays the two versions of the block side-by-side and asks you to pick one to keep: the primary version, or your changed version. If necessary, you can edit the block manually to incorporate elements of both versions.
Some types of conflict are not identified by GitBook. For example, if your edit refers to other content, such as an existing image or definition higher up the page, you should check that this content still exists after you update your CR. Also, if a page you edited was renamed in the primary space, when you update the CR you might find that you are left with two copies of the page, each with a different name and different content. If this happens, you’ll have to delete one copy of the page and potentially transfer some of its contents to the other copy.
Each change request should focus on a single topic. This makes it easier to review and merge quickly, which reduces the likelihood of conflicts occuring, and makes it easier to resolve conflicts if they do occur.
Creating new pages and groups
If you hover the cursor over an existing page or group in the summary, a More actions (⋮) button appears, which reveals a menu with the option to Insert subpage. This creates a new empty page nested under the parent page or group. Similarly, if you hover between pages in the summary, an Add (+) button appears, which enables you to insert a new page between neighboring pages.
To create a group, use the Add new option at the bottom of the summary. This button can also be used to create top-level pages (i.e. pages that are not subpages of another page or group). Once created, you can then drag the new page or group to the correct position in the summary.
If GitHub sync is enabled and you create a new subfolder or Markdown file in the repository, you must manually add it to SUMMARY.md for GitBook to become aware of it.
Importing pages from the old handbook
When you hover the cursor over an existing page or group in the summary, the More actions (⋮) menu button that appears also contains an option to Import subpages. Using this option, you can choose a Markdown or HTML file on your computer to upload and turn into a new subpage.
To create the Markdown or HTML file:
Visit a page of the old handbook and use the option to Edit.
Copy the title and source text and paste them at https://shoogle.github.io/gitbookify/.
Click "Convert" and save the resulting file somewhere on your machine.
Once on GitBook, the page will likely have problems, such as:
Links to other handbook pages are broken.
Images are "hotlinked" from MuseScore.org rather than uploaded to GitBook.
If importing HTML rather than Markdown:
<h1> elements are incorrectly imported as Heading 2. (<h2> and <h3> are imported correctly.)
Some "dodgy" content added by the community.
These issues must be fixed manually, but we don't need to do it yet because we'll do another import later, after the old handbook has been frozen. Before then, we need to get used to GitBook ourselves and then inform the community about the migration.
Editing a page
GitBook uses a block-based editor somewhat similar to Squarespace and recent versions of Wordpress. You can try creating blocks on the Sandbox for experimenting page.
Content blocks
A new block is created for each:
Etc.
If you hover the cursor over an existing block, this reveals a plus (+) button to add a new block, as well as an options (⠿) button with options for the current block. The options button can also be dragged to reposition the block on the page.
Another way to create a block is to edit an existing block and press Enter or Return. This usually creates a new paragraph block below the first one, but it might create something else, such as a new list item or table row. If it's a list item, you can press Tab and Shift+Tab to change the level of nesting, and Enter or Return to convert it to a normal paragraph (this only work while the block is empty).
While editing an empty block, you can type a forward slash (/) to quickly convert it to a different type of block. If the block is not empty, typing slash (/) instead reveals options for inserting inline content.
Last updated
Was this helpful?