Using GitBook
Last updated
Was this helpful?
Last updated
Was this helpful?
User content on GitBook is always owned by an . In our case, that's .
Within an organization, you can create for different content. We currently have one space called , 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").
To make a space viewable to the public, it must be added to a (aka 'site'). We currently have one site called . This site will be used for the source space and all translations.
Now that the handbook site is published, it is available at:
(canonical site URL)
(alias because it's set as the default site for this organization)
(because we set up a )
While a site is published, on its spaces are disabled, so all changes must be made though (or on GitHub if GitHub sync is enabled).
The content within a space can be 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.
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.
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.
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.
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.
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.
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.
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.
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:
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.)
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.
GitBook uses a block-based editor somewhat similar to Squarespace and recent versions of Wordpress.
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.
While GitHub sync is enabled, are disabled, so all changes must be made though , or on GitHub via pull requests or direct commits to the repository.
You're viewing a page now. This page is actually a subpage of the . It's also possible to have subsubpages, and so on.
GitBook has a 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.
While live edits are disabled, the only way to make changes is via a , 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.
Visit a page of the and use the option to Edit.
Copy the title and source text and paste them at .