If your page is structured like a post (e.g About page, blog posts, etc), you should opt create the majority of the content in markdown under its own directory under content/ and use an existing template. Only create a new template if an existsing one doesn't meet your needs or can't be modified to fit your needs.
For pages that making heavy use of HTML, macros and/or partials, you should make create the majority of the content in the template itself like how the home page was made (index.html). You will still need create a markdown file for it in order to set up the front matter. You just don't need to write any markdown inside of it.
Sections have pages under its directory. See content/blog/_index.md for an example of them. A section's index page is named _index.md.
Pages can either have a unique name under a section's directory e.g content/blog/vala-0.56.md or be named index.md. If named index.md, they will have the same URL as the path they are under. The latter option is useful for creating one-off page like the about page (content/about/index.md).
By default, all pages are under the root section which is the website's index page (content/_index.md).
There are two types of components you can create:
- Partials - Don't let you pass data in. 1 file = 1 partial.
- Macros - Allow you to pass data in. Muliple macros can exist in one file.
It's up to you how you to decide to use these types of components to build up these pages. Each type has its advantages and disadvantages.
A macros in head.html called og_data and og_data_with_image take care of this for you. It handles the creates the Open Graph tags and adds the description meta tag for you. It's recommended that you assign the parameters to the page/sections's variables in templates you make.
In all pages make sure that you fill in contain the following fields:
titledate(In the format of YYYY-MM-DD)description
These are used when displaying the in link embeds.
As well as the fields to include when creating pages in general, if the article is written from the context of a single person or group of people, you also should inlcude the extra.authors field with an array of strings (containg names).
Filling the extra.authors field is not mandatory though. By default, the author will be set to "The Vala Team"
These are used when displaying the posts across the site and also in link embeds.
You don't need to create a <h1> in your markdown content. The value you have set in the title field of the front matter will be used in a <h1> that is part of the blog post template.
The showcase is rendered from a partial in templates/partials/showcase.html.
The actual data used to add each item to the showcase is in assets/showcase-items.json.
It's an array where each item is an JSON object with the following fields:
name- Name of the itemicon_path- Where the icon is relative to the website's repository.url- Where the user goes whe they click on the item
Here's an example:
[
{
"name": "elementary OS",
"icon_path": "icons/showcase/elementary.svg",
"url": "https://elementary.io/"
},
{
"name": "GNOME Boxes",
"icon_path": "icons/showcase/gnome-boxes.svg",
"url": "https://apps.gnome.org/en-GB/app/org.gnome.Boxes/"
},
{
"name": "Planner",
"icon_path": "icons/showcase/planner.svg",
"url": "https://useplanner.com/"
},
{
"name": "Starfish",
"icon_path": "icons/showcase/starfish.svg",
"url": "https://appcenter.elementary.io/hr.from.josipantolis.starfish/"
},
{
"name": "BirdFont",
"icon_path": "icons/showcase/birdfont.svg",
"url": "https://birdfont.org/"
},
{
"name": "Peek",
"icon_path": "icons/showcase/peek.svg",
"url": "https://github.com/phw/peek"
}
]