Member Resources Style Guide

A few guidelines to keep things smart and stylish.

For general usage questions, see the official documentation for BookStack (the software this site uses)

Organization

Headers automatically create a linked hierarchy, which can be used as a table of contents.

Use callouts to draw the eye to important information.

Info: Use this to attribute an article to a source

Success: Great for highlighting winning strategies

Warning: A mild heads up, i.e. some of the info on this page is outdated, or in the process of being cleaned up.

Danger: You can't touch this

For example, mark sensitive documents with the following:

Internal Use Only

Formatting

When copying text from an external document, strip the text colors and highlight colors. They interfere with the site theme (especially in Dark Mode).

---

Delete extraneous line breaks. The site already introduces a generous break between paragraphs, so additional returns add too much negative space.

Links and attachments

When a link takes you to a document, slide show or a PDF hosted elsewhere, save that item in a reasonably compatible format and upload it as an attachment. Link to the attached version.

If a link is pointing to an external website that seems ephemeral and not suited to attachment (i.e. a blog, news article or social media post), consider using the Wayback Machine at archive.org to grab a snapshot. You can link to that instead of the live page, in case it goes down or is moved in the future.

Tables

With a little manual effort, tables can be adapted into normal text via indents or bullet lists, which will scale better to different devices. Tables are a problem for mobile browsers.

Compare the Member-Leader Roles Guide to the original for an example of one way to alter a table-heavy article

Reusing Page Content

Occasionally, it may make sense to replicate a page in more than one chapter. Instead of duplicating all the content, it's possible to have one page dynamically include the content of another page. The advantage is that if that content needs to be changed, you only have to change it in one place. See the official documentation for the necessary steps.

Tags

The tags feature can make it easy to find multiple pages that hew to a similar theme, even if they're not grouped in the same chapter. So far, the Safety tag is being added to anything that deals with potentially dangerous situations.

Comments

If you're in the process of making changes or considering the best way to proceed, add a comment down below to share your thought process! Once the comment is no longer relevant, it can be archived (in case seeing that past thinking might be useful) or deleted (if it wouldn't make sense at all without its former context).