📗 Webkit Manual

Content

1. Background

2. Core features

3. Creating a page

4. Views

5. Collections

6. Smart Templates

7. Support


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

  1. 2019 Sites were designed manually, each required a build and deployment and a pre-configured in a locally stored JSON file before build.
  2. 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.
  3. 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.
  4. 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:

  ![](https://source.unsplash.com/random)
  # 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

  1. Upload the image as usual and save.
  2. Hover with your mouse on the saved image, and right-click it, then copy the URL.
  3. 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:

  1. Inline content inside the post
  2. Structured data (markdown table or JSON) in a separate post
  3. 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
  ![image](https://source.unsplash.com/random/500x300)
  Deinde prima illa, quae in congressu solemus
  
  ---
  
  [Box 4](https://edgeryders.eu/t/webkit-manual/13594)
  ![image](https://source.unsplash.com/random/300x100)
  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
: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 https://source.unsplash.com/random/500x300
Box 4 Deinde prima illa, quae in congressu solemus https://source.unsplash.com/random/500x300 https://github.com/edgeryders/webkit

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>

  ![caption for image 1](https://images.unsplash.com/photo-1541661538396-53ba2d051eed?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=882&q=80)
  ![caption for image 2](https://images.unsplash.com/photo-1615149956009-f9fa32fc75e5?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=1950&q=80)
  ![caption for image 3](https://images.unsplash.com/photo-1496096265110-f83ad7f96608?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=1950&q=80)
  ![caption for image 4](https://images.unsplash.com/photo-1604076850742-4c7221f3101b?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=934&q=80)
  ![caption for image 5](https://images.unsplash.com/photo-1458682625221-3a45f8a844c7?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=1867&q=80)

  </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
  ![](https://images.unsplash.com/photo-1567095761054-7a02e69e5c43?ixid=MXwxMjA3fDB8MHxzZWFyY2h8NHx8YWJzdHJhY3R8ZW58MHx8MHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=900&q=60)

  ---

  [Title + Link text for Slide 2](https://edgeryders.eu)
  Some text for Slide 1
  ![](https://images.unsplash.com/photo-1515405295579-ba7b45403062?ixid=MXwxMjA3fDB8MHxzZWFyY2h8MTR8fGFic3RyYWN0fGVufDB8fDB8&ixlib=rb-1.2.1&auto=format&fit=crop&w=900&q=60)

  ---

  [Title + Link text for Slide 3](https://github.com)
  Some text for Slide 3
  ![](https://images.unsplash.com/photo-1617640704063-7f7e2432c651?crop=entropy&cs=tinysrgb&fit=crop&fm=jpg&h=230&ixlib=rb-1.2.1&q=80&w=530)

  </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

  1. 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.

  2. Choose a colour for the project. In the same Edit section click General and select a Background color.

  3. 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.

  4. 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

:warning: 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:

  1. A page must be tagged page
  2. A documentation post must be tagged manual or doc
  3. 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 “https://start.edgeryders.eu/read/” 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 “https://start.edgeryders.eu/event/” 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.

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:

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.

4 Likes
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
: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 https://source.unsplash.com/random/500x300
Box 4 Deinde prima illa, quae in congressu solemus https://source.unsplash.com/random/500x300 https://github.com/edgeryders/webkit
1 Like

@noemi @MariaEuler @estragon

1 Like
"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"}
]

	"data": [{
			"title": "Entry 1 title",
			"subtitle": "Entry 1 subtitle",
			"text": "Uterque enim summo bono fruitur, id est voluptate. Collatio igitur ista te nihil iuvat. Non pugnem cum homine, cur tantum habeat in natura boni; Audio equidem philosophi vocem, Epicure, sed quid tibi dicendum sit oblitus es. Sed venio ad inconstantiae crimen, ne saepius dicas me aberrare; Sin dicit obscurari quaedam nec apparere, quia valde parva sint, nos quoque concedimus; Quae sequuntur igitur? Idem adhuc; Sin kakan malitiam dixisses, ad aliud nos unum certum vitium consuetudo Latina traduceret. Quodsi ipsam honestatem undique pertectam atque absolutam.",
			"url": "https://edgeryders.eu",
			"image": "https://images.unsplash.com/photo-1484589065579-248aad0d8b13?ixid=MXwxMjA3fDB8MHxzZWFyY2h8MTl8fGFic3RyYWN0fGVufDB8fDB8&ixlib=rb-1.2.1&auto=format&fit=crop&w=900&q=60"
		}, {
			"title": "Entry 2",
			"subtitle": "Entry 2 subtitle ",
			"text": "Sed eu semper ex, non gravida ligula.Donec et sem quis leo ultricies scelerisque sagittis vitae arcu.Vivamus gravida nec ex quis pretium.Sed vehicula dolor maximus ex finibus ultrices.Cras egestas leo odio, eget vehicula quam venenatis id.Ut luctus vitae ante eget tristique",
			"url": "https://edgeryders.eu",
			"image": ""
		},
		{
			"title": "Entry 3 title",
			"subtitle": "Entry 3 subtitle",
			"text": "Quantum Aristoxeni ingenium consumptum videmus in musicis? Quamquam id quidem, infinitum est in hac urbe; Satisne ergo pudori consulat, si quis sine teste libidini pareat? Sin laboramus, quis est, qui alienae modum statuat industriae?",
			"url": "https://edgeryders.eu",
			"image": "https://images.unsplash.com/photo-1533735380053-eb8d0759b24a?ixid=MXwxMjA3fDB8MHxzZWFyY2h8MjV8fGFic3RyYWN0fGVufDB8fDB8&ixlib=rb-1.2.1&auto=format&fit=crop&w=900&q=60"
		}
	]

@owen, there are two small problems with the current version of the webkit. I document it here because the GitHub seems dead.

One: when I open a website, the browser tab reads “undefined”.

Two: the footer shows up in the menu as “contact us”. This is bad enough, because most of that footer is called “Terms of Participation and Privacy Policy”. On top of that, if you figure out you are supposed to click on the text on the right side, you are still going nowhere: “Email” goes to Nadia, "Telegram, to a channel where you can mostly receive and not connect, “Twitter” to the Twitter account. Marina, for example, is on none of these channels. Please take those links away, so each site can add its own “contact us” section. And hide the menu item, which is just visual clutter.

Please confirm?

Adding partner logos to events: Hi Owen I think at some point we discussed how to add partner logos to event pages, but I am unsure as to whether this was ever implemented? As it stands now I attempted to add the logos inside the event topic itself, but they do not display. So for this page, to have the logos in the bottom show up as partners, what would the syntax be?