How this 'gitbook' works

Explain how to add content, embed, groups vs pages vs subpages, how we're organizing it, how/who to join/invite, , payment/cost, the link with git/github (for tech people), formatting tweaks

What is this Gitbook (wiki) and what is it for?

Rather than chains of disconnected emails and many unlinked Google docs, I (David Reinstein) thought it would be better to organize our project with this well-structured format.

Who has access/how to gain access?

This version is currently PUBLIC but unlisted. It doesn't contain information on on our trials or marketing activities (as of 18 Jan 2022), but we hope to be adding and integrating some details soon. We hope to make most of this public in due time, in line with information sharing and open science.

What do the sections and groups mean?

"Groups" can hold multiple pages and pages can have sub-pages. But groups cannot have subgroups and the groups have no direct link (while pages do). (In the 'git repo' groups seem to be represented by folders).

How do I edit it and add content?

Getting started

If you have 'write (Editor) access' ....

Update: as of 15 Oct 2021 Gitbook has changed its protocols. You now need to

  • click the icon in the upper right to 'start a change request',

  • and then 'submit' this request when you are ready (ideally, with a brief informative message explaining what you have done.

Give it a try. Once you 'submit', you, or someone else can 'merge' it in.

In newly created blocks/elements "command-slash" (on mac) brings up a lot of cool options (scroll down)

Typing the "@" symbol offers a quick way to link other pages in this book

Merges and conflicts

If you have the Administrator status, you can merge in your own, or others' changes.

What if I get a 'conflict'? If 2 people edit simultaneously and both make changes they try to merge in, this can happen. It should be simple enough to resolve. Just find the icon for the bits indicating a conflict, and choose which version you want to keep.

It should be simple enough to resolve.

Just find the icon for the bits indicating a conflict in the outline bar (that arrow triangle thing), go to that section/those sections, and choose which version you want to keep.

Technical: Connections with Git/Github and coding

This Gitbook is connected to the private github-hosted repo here:

It 'backs up' nicely to a set of easy-to-follow markdown files and folders. If you prefer to work offline, in nice 'raw text formats' (rather than via the web interface)... you should be able to edit those files in any interface and push/merge the content in. (If you are familiar with git and Github. The markdown and project organization syntax is a little bit distinct from others I've used, such as Rmd/bookdown. \

The folders have meaning for the structure of sections, I think, but the file seems to govern most of it. \

There is a particular dash-separated 'description' section at the top of each .md And there are some special code elements like

{% ="URL HERE" %}

<div data-gb-custom-block data-tag="hint" data-style='info'> Hint content here </div>

Last updated