Stop using weird Haml break for changelog preview

It’s really not worth the double filter call and I’m sure I can find
some way to use Middleman to extract this into a method.
This commit is contained in:
Olivier Lacan 2017-04-05 05:27:12 -04:00
parent 0d8d117670
commit fcce20efff
16 changed files with 137 additions and 149 deletions

View File

@ -16,9 +16,8 @@ version: 0.3.0
Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený
seznam podstatných změn pro každou verzi daného projektu. seznam podstatných změn pro každou verzi daného projektu.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Co je smyslem changelogu? ### Co je smyslem changelogu?
Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které
byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu. byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.

View File

@ -17,9 +17,8 @@ version: 0.3.0
Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen)
des Projekts umgesetzt wurden. des Projekts umgesetzt wurden.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Was ist der Zweck eines Changelogs? ### Was ist der Zweck eines Changelogs?
Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche
zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen. zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

View File

@ -16,9 +16,8 @@ version: 0.3.0
A change log is a file which contains a curated, chronologically ordered A change log is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project. list of notable changes for each version of a project.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Whats the point of a change log? ### Whats the point of a change log?
To make it easier for users and contributors to see precisely what To make it easier for users and contributors to see precisely what
notable changes have been made between each release (or version) of the project. notable changes have been made between each release (or version) of the project.

View File

@ -12,14 +12,13 @@ version: 0.4.0
Version **#{current_page.metadata[:page][:version]}** Version **#{current_page.metadata[:page][:version]}**
### Whats a change log? ### Whats a changelog?
A change log is a file which contains a curated, chronologically ordered A changelog is a file which contains a curated, chronologically ordered
list of notable changes for each version of a project. list of notable changes for each version of a project.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown ### Whats the point of a changelog?
### Whats the point of a change log?
To make it easier for users and contributors to see precisely what To make it easier for users and contributors to see precisely what
notable changes have been made between each release (or version) of the project. notable changes have been made between each release (or version) of the project.
@ -33,10 +32,10 @@ version: 0.4.0
contributors should care, and the motivations behind this project. contributors should care, and the motivations behind this project.
If you can spare the time (1:06), its a good listen. If you can spare the time (1:06), its a good listen.
### What makes a good change log? ### What makes a good changelog?
Im glad you asked. Im glad you asked.
A good change log sticks to these principles: A good changelog sticks to these principles:
- Its made for humans, not machines, so legibility is crucial. - Its made for humans, not machines, so legibility is crucial.
- Easy to link to any section (hence Markdown over plain text). - Easy to link to any section (hence Markdown over plain text).
@ -76,15 +75,15 @@ version: 0.4.0
it differently. "2012-06-02" works logically from largest to smallest, doesn't it differently. "2012-06-02" works logically from largest to smallest, doesn't
overlap in ambiguous ways with other date formats, and is an overlap in ambiguous ways with other date formats, and is an
[ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it
is the recommended date format for change logs. is the recommended date format for changelogs.
Theres more. Help me collect those unicorn tears by Theres more. Help me collect those unicorn tears by
[opening an issue][issues] [opening an issue][issues]
or a pull request. or a pull request.
### Is there a standard change log format? ### Is there a standard changelog format?
Sadly, no. Calm down. I know you're furiously rushing to find that link Sadly, no. Calm down. I know you're furiously rushing to find that link
to the GNU change log style guide, or the two-paragraph GNU NEWS file to the GNU changelog style guide, or the two-paragraph GNU NEWS file
"guideline". The GNU style guide is a nice start but it is sadly naive. "guideline". The GNU style guide is a nice start but it is sadly naive.
There's nothing wrong with being naive but when people need There's nothing wrong with being naive but when people need
guidance it's rarely very helpful. Especially when there are many guidance it's rarely very helpful. Especially when there are many
@ -96,7 +95,7 @@ version: 0.4.0
real software projects. Please take a look around and remember that real software projects. Please take a look around and remember that
[discussions and suggestions for improvements are welcome][issues]! [discussions and suggestions for improvements are welcome][issues]!
### What should the change log file be named? ### What should the changelog file be named?
Well, if you cant tell from the example above, `CHANGELOG.md` is the Well, if you cant tell from the example above, `CHANGELOG.md` is the
best convention so far. best convention so far.
@ -107,24 +106,24 @@ version: 0.4.0
### Why cant people just use a `git log` diff? ### Why cant people just use a `git log` diff?
Because log diffs are full of noise — by nature. They could not make a suitable Because log diffs are full of noise — by nature. They could not make a suitable
change log even in a hypothetical project run by perfect humans who never make changelog even in a hypothetical project run by perfect humans who never make
typos, never forget to commit new files, never miss any part of a refactoring. typos, never forget to commit new files, never miss any part of a refactoring.
The purpose of a commit is to document one atomic step in the process by which The purpose of a commit is to document one atomic step in the process by which
the code evolves from one state to another. The purpose of a change log is to the code evolves from one state to another. The purpose of a changelog is to
document the noteworthy differences between these states. document the noteworthy differences between these states.
As is the difference between good comments and the code itself, As is the difference between good comments and the code itself,
so is the difference between a change log and the commit log: so is the difference between a changelog and the commit log:
one describes the *why*, the other the how. one describes the *why*, the other the how.
### Can change logs be automatically parsed? ### Can changelogs be automatically parsed?
Its difficult, because people follow wildly different formats and file names. Its difficult, because people follow wildly different formats and file names.
[Vandamme][vandamme] is a Ruby gem [Vandamme][vandamme] is a Ruby gem
created by the [Gemnasium][gemnasium] team and which parses created by the [Gemnasium][gemnasium] team and which parses
many (but not all) open source project change logs. many (but not all) open source project changelogs.
### Why do you alternate between spelling it "CHANGELOG" and "change log"? ### Why do you alternate between spelling it "CHANGELOG" and "changelog"?
"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a
historical convention followed by many open source projects. Other historical convention followed by many open source projects. Other
examples of similar files include [`README`][README], [`LICENSE`][LICENSE], examples of similar files include [`README`][README], [`LICENSE`][LICENSE],
@ -135,7 +134,7 @@ version: 0.4.0
metadata about the project, they could be useful to anyone intending to use metadata about the project, they could be useful to anyone intending to use
or contribute to it, much like [open source project badges][shields]. or contribute to it, much like [open source project badges][shields].
When I refer to a "change log", I'm talking about the function of this When I refer to a "changelog", I'm talking about the function of this
file: to log changes. file: to log changes.
### What about yanked releases? ### What about yanked releases?
@ -149,14 +148,14 @@ version: 0.4.0
notice it. Since it's surrounded by brackets it's also easier to parse notice it. Since it's surrounded by brackets it's also easier to parse
programmatically. programmatically.
### Should you ever rewrite a change log? ### Should you ever rewrite a changelog?
Sure. There are always good reasons to improve a change log. I regularly open Sure. There are always good reasons to improve a changelog. I regularly open
pull requests to add missing releases to open source projects with unmaintained pull requests to add missing releases to open source projects with unmaintained
change logs. changelogs.
It's also possible you may discover that you forgot to address a breaking change It's also possible you may discover that you forgot to address a breaking change
in the notes for a version. It's obviously important for you to update your in the notes for a version. It's obviously important for you to update your
change log in this case. changelog in this case.
### How can I contribute? ### How can I contribute?
This document is not the **truth**; its my carefully considered This document is not the **truth**; its my carefully considered

View File

@ -16,9 +16,8 @@ version: 0.3.0
Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto. Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Cuál es el propósito del change log? ### Cuál es el propósito del change log?
Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto. Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto.

View File

@ -17,9 +17,8 @@ version: 0.3.0
une liste triée chronologiquement des changements notables pour chaque une liste triée chronologiquement des changements notables pour chaque
version dun projet version dun projet
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Quel est lintérêt dun change log ? ### Quel est lintérêt dun change log ?
Il permet aux utilisateurs et aux contributeurs de voir plus simplement Il permet aux utilisateurs et aux contributeurs de voir plus simplement
les changements notables qui ont été réalisés entre chaque publication les changements notables qui ont été réalisés entre chaque publication

View File

@ -13,9 +13,8 @@ language: it-IT
Un change log è un file che contiene una lista curata e ordinata cronologicamente Un change log è un file che contiene una lista curata e ordinata cronologicamente
delle modifiche degne di nota per ogni versione di un progetto. delle modifiche degne di nota per ogni versione di un progetto.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### A cosa serve un change log? ### A cosa serve un change log?
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
importanti sono state fatte tra ogni release (o versione) del progetto. importanti sono state fatte tra ogni release (o versione) del progetto.

View File

@ -52,6 +52,9 @@
for now and for now and
= link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues" = link_to "help translate ", "https://github.com/olivierlacan/keep-a-changelog/issues"
it. it.
- content = Haml::Filters::Code.render(yield)
= Redcarpet::Markdown.new(Redcarpet::Render::HTML_TOC.new(nesting_level: 5), { with_toc_data: true }).render(content).html_safe
= yield = yield
%footer.clearfix{role: "banner"} %footer.clearfix{role: "banner"}

View File

@ -15,9 +15,8 @@ version: 0.3.0
### Czym jest changelog? ### Czym jest changelog?
Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu. Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Co jest celem prowadzenia changelogu? ### Co jest celem prowadzenia changelogu?
Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu. Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu.

View File

@ -18,9 +18,8 @@ version: 0.3.0
cronologicamente, de mudanças significativas para cada versão de um projeto cronologicamente, de mudanças significativas para cada versão de um projeto
open source. open source.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Para que serve um *change log*? ### Para que serve um *change log*?
Para facilitar para os usuários e contribuidores verem precisamente quais Para facilitar para os usuários e contribuidores verem precisamente quais

View File

@ -18,9 +18,8 @@ version: 0.3.0
хронологическом порядке список значимых изменений для каждой версии проекта с хронологическом порядке список значимых изменений для каждой версии проекта с
открытым исходным кодом. открытым исходным кодом.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Для чего нужен лог изменений? ### Для чего нужен лог изменений?
Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно

View File

@ -16,9 +16,8 @@ version: 0.3.0
Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen
seznam opaznih sprememb za vsako verzijo projekta. seznam opaznih sprememb za vsako verzijo projekta.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Kaj je smisel dnevnika sprememb? ### Kaj je smisel dnevnika sprememb?
Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere
opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta. opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.

View File

@ -16,9 +16,8 @@ version: 0.3.0
En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad
lista över ändringar för varje version av ett projekt. lista över ändringar för varje version av ett projekt.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Vad är meningen med en ändringslogg? ### Vad är meningen med en ändringslogg?
För att göra det enkelt för användare och medarbetare att se exakt vilka För att göra det enkelt för användare och medarbetare att se exakt vilka
viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet. viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.

View File

@ -14,9 +14,8 @@ version: 0.3.0
Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla
sıralanmış, önemli değişikliklerin bir bütünüdür. sıralanmış, önemli değişikliklerin bir bütünüdür.
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### Değişikliklerin kayıtlarını tutmanın anlamı ne? ### Değişikliklerin kayıtlarını tutmanın anlamı ne?
Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler)
arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar. arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

View File

@ -17,9 +17,8 @@ version: 0.3.0
这个列表记录所有版本的重大变动。 这个列表记录所有版本的重大变动。
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### 为何要提供更新日志? ### 为何要提供更新日志?
为了让用户和开发人员更好知道每一个版本有哪些区别。 为了让用户和开发人员更好知道每一个版本有哪些区别。

View File

@ -17,9 +17,8 @@ version: 0.3.0
這個列表記錄所有版本的重大變動。 這個列表記錄所有版本的重大變動。
%pre.changelog= File.read("CHANGELOG.md") <pre class="changelog">#{File.read("CHANGELOG.md")}</pre>
:markdown
### 為何要提供更新日誌? ### 為何要提供更新日誌?
為了讓用戶和開發人員更好知道每一個版本有哪些區別。 為了讓用戶和開發人員更好知道每一個版本有哪些區別。