Help:Changelog
Create a changelog entry.
The “Community Changelog” shows the history of our community. Every entry is added as its own page, but will be rendered as one linear timeline.
Location
| Directory | Description |
|---|---|
| content/<Language>/changelog/ | The “Changelog” entries of the about page |
| content/<Language>/changelog/_index.md | The upper part of the Changelog page |
Create a New Changelog Page
To create a new page, use the command npm run create -- 'changelog/<pageName>.md'.
After that you can edit your newly created page, which is located in content/en/changelog/<pageName>.md.
Example
Create a new page foo:
$ npm run create -- 'changelog/foo.md'
>[email protected] create
> exec-bin node_modules/.bin/hugo/hugo new "changelog/foo.md"
Content "/home/username/path_to_repository/repository_root_directory/content/en/changelog/foo.md" created
Front Matter
Every Markdown file contains a header section, called front matter, in the YAML format to configure parts of the page or website. A changelog page needs the following variables in the front matter.| Variable | Type | Description |
|---|---|---|
title | str | The title of the page or ressource |
date | datetime | The datetime the page was created |
lastmod | datetime | The datetime the page was modified. Should be the same as date when the creating a new page |
contributors | list of
str | A list of contributors |
draft | bool | flase shows the page, true hides the page,
as it does not exist |
blog_post | str | The title of a blog post, which is available on that subject |
The Datetime Type
The date and time according to ISO 8601 . The following table shows the extended format specified in ISO 8601 we use for our website to specify, when e.g. a page was created or edited. It has three parts:
- the date
- the time, including it's designator
T - the timezone offset
| Value | Optional | Description |
|---|---|---|
2021 | No | Year |
07 | No | Month |
08 | No | Day of the month |
T | No | T is a designator, which indicates the start of the time representation |
12 | No | Hour |
34 | No | Minute |
56 | No | Second |
+ or - | Yes | + for a positive or - a negative timezone
offset |
01 | Yes | Timezone offset in hours |
02 | Yes | Timezone offset in minutes |
Formatting Examples
The following example uses the values from the table to show the format. It does not use the actual UTC. If you are not using the timezone offset, you must calculate UTC yourself.
- Example with timezone offset:
2021-07-08T12:34:56+01:02 - Example without timezone offset:
2021-07-08T12:34:56
Header Example
Remember, the front matter is aYAML structure embedded into the
Markdown file. The --- delimiters signal Hugo that this is a front
matter in the YAML format. Here is a generated example, how the
front matter might look like:
---
title: "MyTitle"
date: 2021-10-08T14:48:42+01:00
lastmod: 2021-10-08T14:48:42+01:00
contributors: ["UserA" "UserB" "UserC"]
draft: false
blog_post: "Hello Wrold"# This is an example for a comment in YAML
---
Code
Below you find the implementation of the layout.
HTML
List Page Layout
Defined in layouts/changelog/list.html.
This code is licensed under the MIT license.
{{/*<!--
Changelog Layout
================
Contributors: Michael Sasser
Maintainer: Michael Sasser
License: MIT
Version: 1
Type: List
LAYOUT: /layouts/changelog/list.html
DOCS: /content/<language>/wiki/Help:Layout_Changelog.md
STYLE: /assets/scss/components/_timeline.scss
Description
-----------
The list layout page for the changelog.
Changelog
=========
Version 1
---------
Initial release
-->*/}}
{{ define "main" }}
<div class="container">
<div class="section pt-5">
<div class="row justify-content-center">
<div class="col">
<article>
<h1>{{ .Title }}</h1>
<p class="lead mb-5">{{ .Params.lead | safeHTML }}</p>
{{- .Content -}}
<ul class="timeline">
{{ range .Data.Pages.ByDate }}
<li class="entry">
<p>
<span class="title">
{{- .Title }}
{{ if eq .Draft true -}}
<span class="badge bg-danger">Draft</span>
{{ end }}
</span>
<span class="date">
🗓️
{{ .PublishDate.Format "Jan 2, 2006" -}}
</span>
</p>
<p>
{{- .Content -}}
{{ range first 1 (where (where .Site.RegularPages.ByDate "Section"
"blog") "Params.title" "==" .Params.blog_post)
-}}
<span class="blog-post-message">
There is a blog post available with more information on
this topic:
</span>
<div class="mt-3 pt-3">
<div class="card">
<div class="card-body">
<h3>
<a
class="stretched-link text-body"
href="{{ .RelPermalink }}"
>{{ .Params.title }}</a
>
</h3>
<p>{{ .Params.lead | safeHTML }}</p>
{{ partial "main/blog-meta.html" . -}}
</div>
</div>
</div>
{{ end }}
</p>
</li>
{{ end }}
</ul>
</article>
</div>
</div>
</div>
</div>
{{ end }}
SASS
Defined in assets/scss/components/_timeline.scss.
This code is licensed under the MIT license.
/*
Changelog Layout
================
Contributors: Michael Sasser
Maintainer: Michael Sasser
License: MIT
Version: 1
Type: List
LAYOUT: /layouts/changelog/list.html
DOCS: /content/<language>/wiki/Help:Layout_Changelog.md
STYLE: /assets/scss/components/_timeline.scss
*/
ul.timeline {
list-style-type: none;
position: relative;
li.entry {
padding-left: 30px;
margin: 80px 0;
span.date {
float: right;
font-size: $font-size-base;
}
span.title {
font-style: bold;
font-size: $font-size-lg;
font-weight: $headings-font-weight;
}
span.blog-post-message {
font-style: bold;
}
}
%entry {
margin-top: 0.35em;
content: "";
background: $body-bg;
border: 4px solid $blue-300;
display: inline-block;
position: absolute;
width: 22px;
height: 22px;
left: 19px;
z-index: 100;
}
li.entry::before {
@extend %entry;
border-radius: 50%;
}
}
ul.timeline::before {
margin-top: 0.35em;
content: "";
background: $gray-600;
display: inline-block;
position: absolute;
left: 29px;
width: 3px;
height: 100%;
z-index: 100;
}
@include color-mode(dark) {
ul.timeline::before {
background: $gray-400;
}
ul.timeline li.entry::before {
background: $body-bg-dark;
}
}
Archetype
Defined in layouts/wiki.md.
This code is licensed under the MIT license.
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
lastmod: {{ .Date }}
contributors: []
draft: true
blog_post: ""
---
Categories | Contributors |
|---|---|
| Help, Contribute and Layout | Michael Sasser |