Editing Tips

This page outlines some tips and guidelines to use when editing pages.

Choosing an Editor

The default editor for this Bookstack wiki has been set to Markdown. If you prefer a more traditional WYSIWYG editor (What You See Is What You Get) similar to microsoft word then at then when editing a page select the "Editing Page" or "Draft Saved ..." button at the top center of the screen and select "Switch to WYSIWYG Editor".

Callouts:

Althoug similar, Bookstack does not use Github Flavoured Markdown (GFM) which might be what most users are used to. The admins of this bookstack have added custom callouts that match the look and style of GFM callouts.

<div class="callout note"> Github Style Note Callout</div>
<div class="callout tip"> Github Style Tip Callout</div>
<div class="callout important"> Github Style Important Callout</div>
<div class="callout warn"> Github Style Warning Callout</div>
<div class="callout caution"> Github Style Caution Callout</div>

If these stop working, contact a Wiki administrator and ask them to look at the "Custom HTML Header" for the bookstack. You can also revert to the default callout styles provided by bookstack.

<div class="callout info">An info message</div>
<div class="callout success">A success message</div>
<div class="callout warning">A warning message</div>
<div class="callout danger">A danger message</div>

Callouts with Code:

Since bookstack forces you to use html tags to use custom callouts, placing code blocks within these callouts requires special care. The back ticks (`) or triple backtick (```) will not be recognized within the callout. To circumvent this use the <pre> and <code> tags around your code. You can use <!-- and --> to avoid a blank line when putting the first line of code on the line after the code tag. Eg.

<div class="callout important">
Important note with some code.
<div style="height: 0.5em;"></div> <!-- Insert a bit of whitespace -->
<pre><code class="language-python"><!-- Continue on next line
-->for i in range(2):
  print("hello")
</pre></code>
</div>

for i in range(2):
  print("hello")

Collapsible Content Blocks

It is possible in Bookmark create collapsible content blocks using the html <details> marker. This is useful in reducing the visual length of pages that contain large amounts of documentation. Regular markdown formatting seems to work within collapsible content blocks. Ex.

<details>
<summary>Content block title visible when collapsed. Click to expand.</summary>

### A Header

You can also include code blocks and syntax highlighting works

'''python
for i in range(4):
  print("sweet it works!")
'''
</details>

for i in range(4):
  print("sweet it works!")