Content
1. Background
Edgeryders Webkit is a tool for the Edgeryders organisation and community members to publish content using Discourse as a database for content. There are many CMS solutions out there, but most of them require a separate database and interface for managing content. Edgeryders being a community, it made sense to use Discourse as the database rather than a standalone solution with little community integration. The goal of the webkit is to make it as easy as possible to write and publish pages, with an emphasis on requiring as little code as possible by the author of the page.
1.1 Development History
- 2019 Sites were designed manually, each required a build and deployment and a pre-configured in a locally stored JSON file before build.
- v.1 The configuration of the site was fetched from embedded JSON code inside a post. This allowed us to experiment with remote configuration, but JSON proved clunky, unintuitive and prone to errors when editing in Discourse.
- v.1.5 Changed the webkit syntax to XML markup, which simplified configurations and enabled a plain text preview of the content in Discourse. This version also introduced a sandbox mode which allowed one deployment of the Webkit to parse any number of sites hosted on the platform.
- v.2 Consolidates the codebase, standardises UI and provides a hierarchical organisation of content through the use of Collections and Smart Templates.
2. Core Features
2.1 Pages
Webkit pages are single page sites that allow you to provide an overview of an idea, feature or initiative. If your purpose is to market an idea, and you want some customisation options in presenting this idea, then you should create a page. If you want to publish information about an event or documentation for a project, do not write a page - Smart Templates fulfil this function more effectively and require zero configuration.
2.2 Collections
Collections aggregate content based on their tag or category. A project collection displays information based on a category in the platform - the pages within that category, the events, the contributors to that category and news items. This allows new visitors to the platform to get a clear overview of the activity and information pertaining to a specific project.
2.3 Smart Templates
Smart Templates are simply pre-designed pages that require no configuration. They are based on the assumption that certain types of content have a standard presentation and require no configuration on the user’s end. As of the current version of the Webkit there are smart templates for events, documentation and articles.
2.4 Views
Views are components that display information in a variety of ways. A view can be an image gallery, a table of data, a slideshow, a coloured background with text, a video and more. They allow pages to go beyond text and display interactive elements.
2.5 XML and Markdown Parser
The Webkit parser reads the configuration of a post, converts it from markdown to HTML and translates it into a sequence of views to display on the page. It also enhances certain markdown elements such as block quotes and links to certain pages (YouTube, Vimeo, GitHub, PDFs).
3. Creating a page
The first step to create a page is to create a new draft on the platform. This draft should be in a category it belongs to.
Tag the post with the word page.
3.1 Creating a header
The header is at the top of the page and typically includes a title, subtitle, image (optional) and buttons (optional). There are two ways of creating the header. The first is with no configuration, simply order the elements in the following manner in your post:
# My title.
Some paragraph text as subtitle.
[My button 1](url) [My button 2](url)
The second method to create a header involves HTML and should be used only if you want to customise how the header looks: namely the font, background colour or image, or to add a second column for an image. Notice also the partners attribute for displaying partner logos in the header.
To do this use the following syntax:
<header background="#1c1f99" partners="[17843,29823]">
<h2 style="font-family: 'Homemade Apple', cursive;">My website title</h2>
<p class="font-bold">Some paragraph text as a subtitle.</p>
<a href="">My Button #1</a> <a href="">My Button #2</a>
<img src="https://source.unsplash.com/random" url="edgeryders.eu" caption="image caption" />
</header>
3.2 Creating titles
Titles are import for separating sections of your page. Use <h2> tags or the equivalent markdown (##) to create primary headers:
## My section title
These titles will also be visible in the menu and allow the user to navigate your page. For this reason it’s a good idea to keep level 2 titles short and concise.
Use h3 (###) and h4 (####) (and so on) for subtitles:
### A level 3 title (will not appear in the menu) - can be as long as I like...
3.3 Styling Text
Write text as you would normally for a post. You can optionally add styling by using html with inline css:
<p style="font-family: monospace; font-size: 40px; font-weight: bold; background: red">
This will display as large bold text with a monospaced font and a red background.
</p>.
Webkit also includes the Tailwind library. This allow you to style elements using minimal class names without css. See the Tailwind documentation to understand which classes to use.
The same example above, with tailwind classes:
<p class="text-xl font-mono font-bold bg-red-800">
This will display as large bold text with a monospaced font and a red background.
</p>
4. Views
Views allow you to insert interactive components in your page. Some views are display automatically, for videos for example. Other require using a syntax to configure them.
A view requires data to be configured for it to display content. There are usually three ways to do this:
- Inline content inside the post
- Structured data (markdown table or JSON) in a separate post
- Tagged posts from the platform
4.1 Generic view
A generic view allows you to customise the look of a section or display text from another topic. You can also create a two column layout this way by using a horizontal rule in markdown (---). Use the styling options explained previously to customise the look (either inline CSS or tailwind classes). If you want the view to fill the full width of the page, use the width attribute.
<view width="100%" style="background: linear-gradient(45deg, rgba(238, 174, 202, 1) 0%, rgba(148, 187, 233, 1) 100%); font-family: 'Open Sans', sans-serif">
<h3>Left column title</h3>
<p class="font-italic">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cur igitur, cum de re conveniat, non malumus usitate loqui? Potius ergo illa dicantur: turpe esse, viri non esse debilitari dolore, frangi, succumbere. Omnes enim iucundum motum, quo sensus hilaretur. Quem Tiberina descensio festo illo die tanto gaudio affecit, quanto L. Duo Reges: constructio interrete. Atque haec coniunctio confusioque virtutum tamen a philosophis ratione quadam distinguitur.
Si qua in iis corrigere voluit, deteriora fecit. Non igitur bene. Atque ab his initiis profecti omnium virtutum et originem et progressionem persecuti sunt. Videsne quam sit magna dissensio? Quid censes in Latino fore? Dat enim intervalla et relaxat.</p>
---
<h4>Si qua in iis corrigere voluit, deteriora fecit. Non igitur bene..</h4>
<img src="https://images.unsplash.com/photo-1616456217534-6115f7a1b085?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=300&ixlib=rb-1.2.1&q=80&w=300" />
</view>
4.2 Grid
Displays a grid of content, useful for feature overviews or summary points. There are two ways to configure a grid.
1. Inline configuration
<grid>
[Box 1](https://edgeryders.eu)
Some text on box 1
---
## :smile: Box 2
Some text on box 2
---
## Box 3
Some text on box 3
</grid>
You can add a visual element to each box such as a discourse emoji (see ‘Box 2’) or an image (see ‘Box 3’).
2. Structured data
Create a separate post within which you’ll insert a markdown table, as shown below. An easy way to create markdown tables is to use the Tables Generator website and copy paste the result into the post.
| title | text | image | icon | url |
|---|---|---|---|---|
| Box 1 | Some text on box 1 | my link to a website | ||
| Box 2 | Some text on box 2 | |||
| Box 3 | Some text on box 3 | url to image |  |
Save the post and note the ID of the post. If the id is 56822 for example, configure your grid like so:
<grid data="56822"/>
The above structured data can also be formatted in JSON if preferred, taking the above example:
"data": [
{
"title": "Box 1",
"text": "Some text on box 1",
"url": "my link to a website"
},
{
"title": "Box 2",
"text": "Some text on box 2",
"icon": " :smile:"
},
{
"title": "Box 3",
"text": "Some text on box 3",
"image": "url to image"
}
]
3. Tag
Providing a tag displays all tagged posts from Discourse in the grid, with the title, date and preview text in each box. If you want to paginate the number of items in the grid use the display attribute.
<grid tag="my_discourse_tag" display="6" />
4.3 Gallery
A gallery walls you to display a grid of photos on a page. These photos are displayed as thumbnails and when clicked on open up in a modal on the page.
1. Inline configuration
<gallery>
</gallery>
2. JSON
<gallery data="15837" />
Topic 15837
"data": [
{
"image": "url_to_image_1",
"text": "caption for image 1"
},
{
"image": "url_to_image_2",
"text": "caption for image 2"
},
{
"image": "url_to_image_3",
"text": "caption for image 3"
}
]
4.4 Slider
A slider is a carousel that display images or posts in a loop. You can configure it to autoplay and display a number of slides at a time.
1. Inline configuration
<slider autoplay="true" display="2">
## Title for Slide 1
Some text for Slide 1
---
[Title + Link text for Slide 2](link url for Slide 2)
Some text for Slide 1
---
[Title + Link text for Slide 3](link url for Slide 3)
Some text for Slide 3
</slider>
2. Tag
Use this to display posts from Discourse in a slider.
<slider tag="my_discourse_tag" />
4.5 Table
Tables allow you to provide a condensed view of data with search. They are useful for providing a high information-density overview of information that is structured with the same pattern. Tables only work with structured data and tags.
1. Structured data
Create a post, in this example it has the ID 15923.
JSON
"data": [
{
"title": "Entry 1 title",
"subtitle": "Entry 1 subtitle",
"text": "Text for entry 1",
"url": "external url for entry 1",
"image": "image url for entry 1"
},
{
"title": "Entry 2 title",
"subtitle": "Entry 2 subtitle",
"text": "Text for entry 2",
"url": "external url for entry 2",
"image": "image url for entry 2"
},
{
"title": "Entry 3 title",
"subtitle": "Entry 3 subtitle",
"text": "Text for entry 3",
"url": "external url for entry 3",
"image": "image url for entry 3"
},
]
Markdown table
| title | subtitle | text | url | image |
|---|---|---|---|---|
| Entry 1 | Entry 1 subtitle | Text for entry 1 | external url for entry 1 | image url for entry 1 |
| Entry 2 | Entry 2 subtitle | Text for entry 2 | external url for entry 2 | image url for entry 2 |
| Entry 3 | Entry 3 subtitle | Text for entry 3 | external url for entry 3 | image url for entry 3 |
Then reference the topic ID where the data is included:
<table data="15923" />
4.6 Forms
Forms are currently disabled pending implementation of the consent requirements. IN practice when ready you will be able to embed a form on the page like so:
<form data="id_of_form" />
5. Collections
Collections are based on discourse categories. They aggregate content in an automatic way that provides a visitor with a birds eye view of a project - that includes pages, news, events, contributors and more. As they are the front facing page of a project, it is recommended to configure them to be presentable.
5.1 Configuring a project page
-
Choose a logo for the project. Go to the category you will use on Discourse and click Edit in the top right (with the wrench icon). Select Images and upload an image in the Category Background Image. The image should be white (or a light colour), and ideally a PNG with transparency.
-
Choose a colour for the project. In the same Edit section click General and select a Background color.
-
Choose a URL for the project. In General, set a category slug - this is important as it is how users will visit the project collection.
-
Include a brief description of the project. In General, click on Edit Description - this will be included in the header of the project page.
5.2 Organising content
Important - Keeping content organised in the category is important to show projects are currently active and enduring that project pages are actually useful to a first time visitor. There are only a handful of things to be mindful of in order to ensure each project page picks up the relevant content to display:
- A page must be tagged
page - A documentation post must be tagged
manualordoc - An event must be tagged
event
For events specifically, ensure each event contains a timestamp of the event at the start of the post for it to be viewed in the calendar:
[date=2021-04-14 timezone="Europe/Brussels"]
For pages: you can apply a thumbnail to a page (Edit the title of the post => select thumbnail) if you would like an image to represent the page in the collection.
Collections are only useful if content is organised in the category. If not they will display no content and be rather useless.
5.3 Sharing a collection
The collection url is simply “https://start.edgeryders.eu/” followed by the category slug you configured. Here are some examples:
6. Smart Templates
Smart templates allow you to publish pages from topics with zero configuration. This is ideal when you simply want to share a post and do not want to spend time thinking about the presentation.
There are currently smart templates for sharing articles, events and documentation.
6.1 Article template
Simply go to “Edgeryders | Start” followed by the topic ID of your post.
Here are some examples:
It is advisable to provide a collection slug in the URL so first time visitors can easily access the category the article belongs to. This encourages platform discovery. To do this, insert the category slug first in the url. This will the be displayed in the menu and direct the user to the relevant project page. Examples:
The article template provides a feature to download the article as a PDF and buttons to share it on social networks. It will also highlight sections of the article if replies contain a quote of the original post.
6.2 Event template
Simply go to “Edgeryders | Start” followed by the topic ID of your post.
Here are some examples:
The same logic applies here: it is advisable to structure the URL to include a category slug to which the event belongs to.
- https://start.edgeryders.eu/scifi-economics/event/15764
- https://start.edgeryders.eu/research-network/event/15770
The event template also provides a function to sync the date and time to the users local calendar and RSVP on the platform.
6.3 Doc template
Simply go to “https://start.edgeryders.eu/doc/” followed by the topic ID of your post.
Here are some examples:
- https://start.edgeryders.eu/collaboration/doc/12786
- https://start.edgeryders.eu/collaboration/doc/11904
Again, make sure you include a category slug (in this case ‘collaboration’) to ensure the user has somewhere to navigate to find other relevant manuals.
The doc template also detects GitHub repository URLs and displays the relevant stats in the sidebar.
6.4 Using views in smart templates
Because smart templates use the same Webkit parser as pages, you can include all of the views mentioned above in articles, events and manuals.
7. Support
For people unfamiliar with the Webkit, or anyone having trouble with a page, there is a weekly support call organised every Monday at 17:00 CET. Save your questions for then and I will do my best to solve your problem.
