Examples
Purpose
lerna --version conventional commits adapter can automate the changelog creation and maintenance, but the generated HTML looks a bit ugly.
This remark plugin attempts to fix that — the plan is to display the changelog in a vertical timeline:
The main part is this plugin extracts the date from the h1/h2 heading and puts it into a new div underneath so that you can position the date to the left of the vertical timeline:
<h2>3.1.0</h2>
<div class="release-date">Aug 12, <span>2022</span></div>
<h3><span class="emoji">✨</span> Features</h3>
<ul>
<li>feature 1</li>
<li>feature 2</li>
</ul>
Additionally, any h1 version headings are turned into h2, and each h3 (Commit type) heading gets an emoji.
The top part, h1 “Change log” (which should be one word) and static sentence “All notable changes to this project…” is removed so that you could format it properly — set the “Conventional Commits” to open in a new tab and so on.
API
This package exports a default, changelogTimeline (you can change it to something else, it’s a default export). Use it like this:
unified().use(changelogTimeline);
Also, you can customise it using an Optional Options Object, which you’d pass as a second argument:
unified().use(changelogTimeline, {
dateDivLocale: "en-UK",
dateDivMarkup: ({ date, year, month, day }) =>
`${month} ${day}, <span>${year}</span>`,
});
The Optional Options Object has the following shape:
The DateParamsObj is the plain object that is passed to your callback function; it has the following shape:
Here are all defaults in one place for copying:
{
dateDivLocale: "en-US",
dateDivMarkup: ({ date, year, month, day }) =>
`${month} ${day}, <span>${year}</span>`,
}
That’s US “month-day” arrangement, but feel free to swap them around as I do on this website.
PS. The span around “year” is necessary to stack it onto the next line on the mobile layout; I set display: block via media query on narrow layouts.
opts.dateDivLocale
We are talking about these dates:
This plugin extracts year, month and day from the markdown, formats them according to your supplied locale and passes them to your callback function, along with the complete date object (in case you need to put more fancy logic).
You can do some fancy processing right there:
unified().use(changelogTimeline, {
// dateDivLocale: "en-US",
dateDivMarkup: ({ date }) => {
const somethingNew = date.toGMTString();
console.log(`in: ${date.toString()}; out: ${somethingNew}`);
return somethingNew;
},
});
But then, it’s cleaner to move such callback into a standalone function (and, ideally, unit-test it):
{
dateDivLocale: "en-US",
dateDivMarkup: ({ date }) => fancyProcessingFunction(date),
}