Content
1. Background
Webkit is a tool for the Edgeryders organisation and community members to publish pages using Discourse. There are many CMS solutions out there, but most of them require a dedicated database and interface for managing content. Edgeryders being first and foremost a community, it made sense to use Discourse as the backend provider 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 to set up a page.
1.1 Development
- 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 Webkit parser
The Webkit parser reads the XML tags inside a post, converts the markdown to HTML and translates the whole into a JSON schema. The parser also enhances certain markdown elements such as block quotes and links to certain content such as YouTube, Vimeo, GitHub or 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 Discourse tag 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)
"Troubleshooting your header image
Notice that the image’s URL needs to be absolute. If you simply upload an image on to the Edgeryders Discourse platform, by default the platform embeds it in your post with a relative URL, like upload://pIVIfKu4qUDlLdn4qIBWPPYrgfs.jpeg. This will not work. Unfortunately, absolute URLs in Discourse are not intuitive: they look something like unless you replace it with https://edgeryders.eu/uploads/default/original/2X/8/pIVIfKu4qUDlLdn4qIBWPPYrgfs.jpeg. Your best bet is to
- Upload the image as usual and save.
- Hover with your mouse on the saved image, and right-click it, then copy the URL.
- Edit your topic, and replace the relative URL (starts with
upload) with the absolute one you have copied. Save.
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.
4.2.1 Inline content
<grid>
[Box 1](https://edgeryders.eu)
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Non pugnem cum homine, cur tantum habeat in natura boni; Utilitatis causa amicitia est quaesita.
---
## :smile: Box 2
Callipho ad virtutem nihil adiunxit nisi voluptatem, Diodorus vacuitatem doloris. Sed in rebus apertissimis nimium longi sumus. Vos autem cum perspicuis dubia debeatis illustrare, dubiis perspicua conamini tollere.
---
## Box 3
Deinde prima illa, quae in congressu solemus
---
[Box 4](https://edgeryders.eu/t/webkit-manual/13594)
Vos autem cum perspicuis dubia debeatis illustrare, dubiis perspicua conamini tollere.
</grid>
You can add a visual element to each box such as a discourse emoji (see ‘Box 2’) or an image (see ‘Box 3’).
4.2.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 |
url |
|---|---|---|---|
| Box 1 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Non pugnem cum homine, cur tantum habeat in natura boni; Utilitatis causa amicitia est quaesita. | https://edgeryders.eu | |
 Box 2 |
Callipho ad virtutem nihil adiunxit nisi voluptatem, Diodorus vacuitatem doloris. Sed in rebus apertissimis nimium longi sumus. Vos autem cum perspicuis dubia debeatis illustrare, dubiis perspicua conamini tollere. | ||
| Box 3 | Deinde prima illa, quae in congressu solemus | https://source.unsplash.com/random/500x300 | |
| Box 4 | Deinde prima illa, quae in congressu solemus | https://source.unsplash.com/random/500x300 | GitHub - edgeryders/webkit: Webkit is a tool for the Edgeryders organisation and community members to publish pages using Discourse. |
Save the post and note the ID of the post. If the id is 13594/3 (meaning post #3 in topic 13594) for example, configure your grid like so:
<grid data="13594/3" />
The above structured data can also be formatted in JSON if preferred, using the above example:
"data": [
{
"title": "Box 1",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Non pugnem cum homine, cur tantum habeat in natura boni; Utilitatis causa amicitia est quaesita.",
"url": "https://edgeryders.eu"
},
{
"title": ":smile: Box 2",
"text": "Callipho ad virtutem nihil adiunxit nisi voluptatem, Diodorus vacuitatem doloris. Sed in rebus apertissimis nimium longi sumus. Vos autem cum perspicuis dubia debeatis illustrare, dubiis perspicua conamini tollere."
},
{
"title": "Box 3",
"text": "Deinde prima illa, quae in congressu solemus",
"image": "https://source.unsplash.com/random/500x300"
},
{
"title": "Box 4",
"text": "Deinde prima illa, quae in congressu solemus",
"image": "https://source.unsplash.com/random/500x300",
"url": "https://github.com/edgeryders/webkit"
}
]
4.2.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="newsletter" display="6" />
4.2.4 Grid options
The following options are available for the Grid view.
| attribute | value | description |
|---|---|---|
| display | integer | the number of items to display, paginates items. |
| tag | string | discourse tag to fetch posts from |
| width | string (default: 100%) | the width of the grid in the page |
| columns | integer | the number of columns in the grid |
4.3 Gallery
A gallery displays a grid of thumbnail images. When clicked on a larger image opens up in a modal on the page.
4.3.1 Inline content
<gallery>
</gallery>
4.3.2 Structured data
<gallery data="13594/5" />
Post 13594/5
"data": [
{ "image": "https://images.unsplash.com/photo-1617301949085-788b443ec77e?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=320&ixlib=rb-1.2.1&q=80&w=300", "text": "caption for image 1"},
{ "image": "https://images.unsplash.com/photo-1616519242962-dc3e64586b3f?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=450&ixlib=rb-1.2.1&q=80&w=300", "text": "caption for image 2"},
{ "image": "https://images.unsplash.com/photo-1616877340448-572b0968dffd?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=500&ixlib=rb-1.2.1&q=80&w=300", "text": "caption for image 3"}
]
4.4 Slider
A slider display images or posts in a loop. You can configure it to autoplay and display a number of slides at a time.
4.4.1 Inline content
<slider autoplay="true">
## Title for Slide 1
Some text for Slide 1
---
[Title + Link text for Slide 2](https://edgeryders.eu)
Some text for Slide 1
---
[Title + Link text for Slide 3](https://github.com)
Some text for Slide 3
</slider>
4.4.2 Tag
Use this to display posts from Discourse in a slider.
<slider tag="newsletter" />
4.5 Table
Tables are useful for providing a high density overview of information that is structured using the same schema. Tables only work with structured data and tags.
1. Structured data
Create a post, with the following structure in JSON:
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"
},
]
Alternatively create a markdown table, as the following:
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="13594/6" />
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 News template
Simply go to “Edgeryders | Start” followed by the topic ID of your post.
Here are some 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.
