Contributing - The Technical Side
Editing, Markdown, images, links, adding a Google doc, two contributors editing simultaneously clashing
- Editing Pages
- Markdown Hints
- Adding Images
- Resizing Images
- Links to pages in Rebel Toolkit
- Adding a Google document
- Same page two + contributors
- Tags and why they're useful
How to edit the pages on the Rebel Toolkit web site. Any rebel with a Communications Hub login can edit pages.
This page explains the nuts and bolts of editing the pages of the Rebel Toolkit. For a more general introduction to the Rebel Toolkit, and suggestions for what you might like to add, see the Toolkit Introduction chapter. You can also make small changes, for example to fix a typo, correct a link or add extra information.
Note that the Rebel Toolkit is visible to everyone on the Internet. Please do not publish personal email addresses, Mattermost invite links or Zoom call details that include the passcode, or links to documents containing such things. It is your responsibility to check any linked documents (eg Google documents) for things which should not be public. And if a Google document has links to other documents, it is probably best not to include a link to it at all.
Signing Up and Logging In
In order to edit the content on this web site, you need to be logged in.
The user accounts on this web site are tied to the accounts on the Communications Hub.
To sign up to this web site, click the 'Sign up' link at the top of the home page. Make sure you click on the SIGN UP WITH UK HUB button first and ignore the name, email and password fields on the Sign Up page. You will need your Hub user name and password, unless you are already logged in to the Hub.
Logging in subsequently is done also with your Hub user name and password. Click on LOGIN WITH XR UK HUB on the Log In page.
New users have the ability to edit any page, so please be careful.
Note that this web site is visible to the general public on the Internet, and is indexed by Google and the other search engines, so:
- Don't add anything that should not be visible.
- If you don't want your full name to be visible, change it by going to Edit Profile on the menu top right.
Please do not include any email addresses unless they are already public on the Internet. This also applies to links to, for example, Google Docs containing email addresses, or other sensitive material.
This web site runs on a software package called BookStack. Their home page is at https://www.bookstackapp.com/. We have our own copy of BookStack running on one of our servers in Switzerland.
The user documentation is at https://www.bookstackapp.com/docs/. We won't duplicate that here, but we will add things which are specific to this site or need extra clarification.
BookStack supports two different page editors called WYSIWYG and Markdown. We have chosen to use the Markdown editor for this site. Note that the BookStack demo referenced on their home page, while good for gaining an understanding of BookStack, is configured to use the WYSIWYG editor. This is a site-wide setting and can't be adjusted per user, because the pages are stored in a different format by the two editors.
To edit a page:
You need to sign up and log in
Then go to the page you want to edit.
Click the Edit button
On very wide screens a sidebar will appear on the right hand side which includes an Edit link.
On medium width screens a sidebar will appear on the left hand side which includes an Edit link.
On narrow screens, you have to click the Info tab at the top of the page to make the sidebar appear.
The editor accepts both Markdown and HTML. You may find that the page that you are editing is in Markdown or HTML or a mixture of both. For example in Markdown a bold word is indicated like this:
**bold words** (rendered as 'bold words'). In HTML, you get the same effect with
<b>bold words</b> (rendered as 'bold words').
For information about Markdown see: https://daringfireball.net/projects/markdown/basics and https://daringfireball.net/projects/markdown/syntax. You may wish to get yourself a summary of the Markdown codes by searching on the Internet for 'Markdown cheat sheet' -- there are lots.
See the Markdown Hints page for more information about Markdown.
For plain text content, no special markup is needed. Put a blank line between paragraphs.
It is a good idea to keep a copy of your text yourself locally in case it gets lost, through computer failure or user action. This can done by clicking in the editing area and doing Ctrl-A (Select All), Ctrl-C (Copy), then open Notepad, Ctrl-V (Paste), Ctrl-S (Save) and choose a place and name for it. These are the instructions for Windows. It will be similar for other operating systems.
When you have made your changes, make them visible by clicking Save Page in the top right hand corner.
Creating New Pages
You can create a new page by going to the Book or Chapter where you want the new page, and clicking New Page in the sidebar. You can change the order of pages by clicking Sort later, which lets you set the exact order you want.
If you are not sure which book your page lives in, please contact the Rebel Toolkit team via Mattermost (see the Contact Us page) and a more experienced editor can advise where it should be created, or create a new Book.
Start your page with a sentence that gives some more detail as to what the page may be about in addition to the title. The first line or two appear in the book contents lists and on search results, so this makes it easier for readers to find the page they want.
Split your text into multiple pages if necessary. If pages are too short, it is hard to find things using find-in-page in your browser, as you have to do it separately for every page. If the pages are too long, they become hard to take in. Also on a long page, you may have so many headings that the Page Navigation on the left (wide screens only -- on a narrow screen it is on the Info tab) becomes taller than the height of a typical screen.
Another way to stop the Page Navigation getting too long is to make headings at the lowest level which don't appear in the Page Navigation by just using a short bold paragraph, like the one above, which looks like a heading but just uses bold markup
Shelves and Books
If you think we should have another Shelf or another Book, please discuss it on the appropriate Mattermost channel or forum first so that we keep some kind of coherence. (Each Shelf needs to have a note of where discussions should be held). For the moment, use the channel and forum described on the Contact Us page.
Only users with the higher level of permissions (Editors) can create new Shelves. Anyone can now create new books, but feel free to ask for advice about the most suitable name and location first.
Markdown is used to make headings, bold, bulleted lists etc on the Rebel Toolkit pages.
This page contains tips for formatting your pages. Feel free to add things which you have found useful but were not obvious from the Markdown and BookStack documentation (see Editing Pages for the links to that documentation).
In addition to classic Markdown, BookStack supports the Markdown Extra extensions, see https://michelf.ca/projects/php-markdown/extra/. This provides a number of extra facilities in addition to the original Markdown, in particular support for tables. Here is a quick example of how to insert a table.
| Item | Value | | --------- | -----:| | Computer | $1600 | | Phone | $12 | | Pipe | $1 |
This renders as:
Link on an Image
For example, this
[![rebel ringers](/uploads/images/gallery/2020-08/thumbs-150-150/RebelRingers.png)](/books/engaging-our-rebels/page/rebel-ringing) renders as:
Floating images to right or leftThe Markup Extra specification says that you should be able to add class attributes to image markup, but it doesn't work in BookStack. You need to put the image in as HTML as below if you want to float an image with the text wrapping round it. You can also use align-left and align-center.
<img src="/uploads/images/gallery/2020-08/thumbs-150-150/RebelRingers.png" alt="Rebel Ringers video" class="align-right">
Horizontal Rules in Dark Mode
Horizontal rules like this:
don't show up in BookStack Dark Mode. There is a link to turn Dark Mode on and off near the top of the sidebar or Info panel on the home page. This is a mistake in the BookStack default style sheet in Dark Mode where the horizontal rule is dark grey (#222) on a dark grey background. We mention it in case it puzzles you. We may or may not fix it.
You can add comments to be seen by subsequent editors of the page, but which will not appear on the final rendered page after the Markdown processing. There is no explicit mechanism for comments in Markdown, but we can make use of the reference-style link syntax like this:
[Comment]: # (you can put any message for editors here.
It can span more than one line)
Not to be confused with the BookStack comment facility, which is turned off.
To add an image to a page:
- prepare a suitably-sized image. Most photos need their resolution reducing for publishing on the web. See the Resizing Images page for instructions,
- click in the text at the point where you want the image to appear,
- click the "Insert Image" button in the editor above the main text pane,
- drag your image from Windows Explorer (or the equivalent for your computer) into the grey area top right where it says "Drop images or click here to upload",
- click on the grey area top right where it says "Drop images or click here to upload", and select an image,
- click on the image you have just uploaded,
- click SELECT IMAGE,
- the Markdown code to display the image will appear in your page.
You can also drag an image file directly into the main text area of the editor. However this not recommended because the image will be given a numeric name, and not the name of the file it came from. If you have done this, you can rename any image via the "Insert Image" button mentioned earlier: click on the image, edit the name and click SAVE. Images can be deleted via the same screen using the dustbin icon.
Please try to use sensible names for your images so that they are easier to manage.
Note that the Rebel Toolkit is not meant as a repository for artwork, photos, videos etc: store such items in the UK Cloud or the Global Media Library, and refer across to them from a page on the Rebel Toolkit.
Why use smaller images?
It saves on energy! Every pixel uses energy to be stored and shared so the smaller the image the less energy you use. It'sgreen.
They take up less space on a page. Pages can be quite long at the best of time onhere so why not make them colourful but also quick to browse!
OK, so how do I do that?
Not a tech whizz (yet)?
If you have an image to put on a page on the Rebel Toolkit, you may need to resize it in order to get it to display at the correct size on the page. This involves reducing the resolution of the image, ie reducing the number of pixels in the width and height.
You do this on your computer before uploading it to the Rebel Toolkit.
Notes for Microsoft computers:
You can see the dimensions of an image by hovering your mouse over the name in Windows Explorer.
- For an image on a web page, right-click and select View Image Info (in Firefox), select Inspect and hover over the image element (in Chrome). In most cases you will want an image between 200 and 600 pixels across.
Notes for Computers with the Paint app:
An easy way to resize an image on a Mac is to open the file using Paint.
Click on the Tab Image on the toolbar at the top of the screen. A drop-down menu will appear with the option to Adjust image. Click on that and choset he amount of pixels you want it to have. 200 Width will make the image take up aboutz a third of the width of a page - to give oyu an idea. This is usually small enough to see but not so big that it takes up lots of room. (You can also use Preview in much the same way)
Once you have resized the image click on the tab File in the Toolbar at the top. Click on Save As and put it into a file where you might find it again easily.
Now you can add a page in the Toolkit and insert an image which is smaller.
Tip: It is a good idea to make a copy of the image and resize the copy.
There are numerous tutorials available on how to resize images, and a selection is listed below.
Many of the tutorials are trying to get you to download a piece of software or to use a particular web site.
You do not need to install any new software or to use a web site or online service*
Whether you use Windows, a Macintosh or Linux, your computer already has the software you need to resize images. The list below only covers Windows.
Feel free to add suggestions for Macintoshes if that is what you use.
*Linux is more tricky, and you may actually want to install some software.
Tutorials for Resizing Images
https://www.howtogeek.com/354015/how-to-resize-images-and-photos-in-windows/ Ignore the "Third Party App" sections and use Paint.
https://tencomputer.com/resize-photos-in-windows-10/ Ignore the "Method 2: Download" section and use Paint.
Using Preview to resize an image tutorial. Youtube video link. You can skip the first 40 seconds where he explains why you may want to change the size of an image.
Links to pages in Rebel Toolkit
Normally the URL (web address) of a page in the Rebel Toolkit includes the name of the book it is in and the name of the page. This can cause problems if you make a link to a page and then the page gets renamed or moved to another book. The Bookstack software keeps a list of old page names, so links sometimes continue to work, but not always.
Each page is actually identified by a number which does not change, and you can use that number in a link.
To find the static link for a page:
Go to the page you want to make a link to
Highlight a piece of text by double clicking on a word. The word gets highlighted.
A pop-up box appears - in that pop-up box you will see the unique address of the page and a fragment identifier. The fragment identifier is the part after the "#" which identifies a particular paragraph within the page.
Copy the address and remove the fragment identifier so you don't want to link to a part of the page.
For example the address of this page is
https://rebeltoolkit.extinctionrebellion.uk/link/463. So you can make a link like this: Links to pages in Rebel Toolkit which will continue to work even if the page is moved.
Adding a Google document
If you have something useful in a Google document which you would like to make available on the Rebel Toolkit, you can't upload it directly. You have a choice:
If the Google document has a lot of complicated formatting, you can just make a short page on the Rebel Toolkit with a description of the document in a few sentences and a link to the Google document. The description just needs to be enough so that people can decide whether to click on the link or not. You can put links to several documents on one page if they are related. Bear in mind that the Rebel Toolkit is visible to everyone on the Internet: do not include links to any document with confidential information, eg personal email addresses.
If you have the time to convert the formatting manually to the markup required on the Rebel Toolkit, you can do that, ie make a page on the Rebel Toolkit containing all the text from the Google document. Some people prefer to make a file in Notepad (or equivalent) on their computer and do all the work on that before pasting it in to the editor on the Rebel Toolkit. That way you are less likely to lose all your work. The formatting needs to be done in accordance with the Editing Pages instructions.
Same page two + contributors
For those that may be working on a doc at the same time as another Rebel.
If at the top of the page you are working on you see an image the one below pop up at the top right-hand corner then we strongly advise that you work on a separate page. There is a possibility that when you save someone loses some of their work.
If more than two people are contributing to the same page at the same time a similar box will appear, all red, and it will name the other user.
The advice is still the same - save your work elsewhere as there is a possibility that when someone saves the work gets lost.
Generally, we recommend working on the Toolkit from a separate doc rather than directly onto the Toolkit. This is advisable because it means you have access to the original doc as back-up.
Tip: You can use the website Remarkable to create docs. It only works with Linux or Windows currently. The benefit of this site is you can write using markdown and it will show you a preview of it as you type. THis means you can write complete docs before uploading them to the Tookit.
Tags and why they're useful
When you create a resource in the Toolkit, you should add one or more "Tag(s)" to help people to find it.
The Toolkit's Shelves are organised in a particular way to reflect an imagined "rebel journey".
However, there will be many times when you, or another rebel, want to group together resources following certain subject areas, or other activities, that draw from a number of different Shelves. Tagging gives you thousands of different ways to combine resources.
Tagging each Page, Book or Chapter that you create allows other Toolkit users to draw together resources in many different ways.
How to add a Tag
On pages you can go to the far right side of the editing screen and open the side bar, revealing the area to use to add a Tag. It looks like this:
A Book (or Chapter) can be Tagged just by selecting "Edit" and adding a tag here:
The following list has been developed to control the number of tags that are used. Whilst you can use any tag you like, we suggest you use at least one tag from this list too.
NB Whilst every Tag listed here is "clickable" i.e. it will search the toolkit for that Tag, this is a new resource, and most of the Tags listed here haven't yet been applied, so will result in a "not found" search.