Markdown output support?

[bruxisma]

Hello,

I was wondering if a bit more support for Markdown might be possible? I've more or less successfully ~tricked~ convinced towncrier to output Markdown for my changelog file, however there's no way to change or enforce the H1 title output in this case. Right now to sort of get around it, I've done the following in my pyproject.toml:

[tool.towncrier]
package = 'dripstone'
package_dir = 'src'
filename = 'CHANGELOG.md'
directory = ".changelog"
template = ".changelog/template.md"
title_format = "# {name} {version} ({project_date})"
issue_format = "#{issue}"
start_string = "<!-- TOWNCRIER -->\n"
underlines = ["<!--- --->", "##", "###"]

This (plus a slight change to the default template to make it more markdown friendly) then gets generated into

# Dripstone 0.1.0 (2018-09-06)
<!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- ---><!--- --->

<!-- TOWNCRIER -->


## Bugfixes

* Fixed Whatever (#1234)
* fixed some more (#12345)

Which is uhhh, a terrible hack and makes me feel uncomfortable. I can try to submit a patch if you'd like, but I'm just curious if this is relevant to the project's goals.

[glyph]

OK I'm curious: what happens if you just have "" as "underlines"?

[bruxisma]

lol, yeah that works. WOOPS

[glyph]

Is this just a ... documentation issue now?

[bruxisma]

I suppose! It'd be nice if I didn't have to set all the fields to get it to work with markdown, but it's not a big deal 🤷‍♀️

[deeplook]

What's the status of Markdown support now, two years later? ;)

[timwsuqld]

@slurps-mad-rips Are you able to share your template.md changes as well? Thanks

[bruxisma]

@timwsuqld it's located here and I haven't touched this project in a long time, and will most likely delete it at some point.

[timwsuqld]

@slurps-mad-rips Thanks for that. I eventually hacked together my own, and looking at yours we came to roughly the same place.

For others trying to implement markdown, here is what I've got somewhat working. My setup has the release's as 2nd level headings, and so the category sections are 3rd level headings. I also put the issue number at the start of the changelog entry with a link to the issue. While this isn't strictly necessary (when viewed in Github/Gitlab it'll auto link), it makes the generated file more useful for us viewing outside of Gitlab/Github.

.towncrier.template.md

{% for section, _ in sections.items() %}
{%- if section %}{{section}}{% endif -%}

{% if sections[section] %}
{% for category, val in definitions.items() if category in sections[section]%}
### {{ definitions[category]['name'] }}

{% if definitions[category]['showcontent'] %}
{% for text, values in sections[section][category].items() %}
- {{ values|join(', ') }} {{ text }}
{% endfor %}

{% else %}
- {{ sections[section][category]['']|join(', ') }}

{% endif %}
{% if sections[section][category]|length == 0 %}
No significant changes.

{% else %}
{% endif %}

{% endfor %}
{% else %}
No significant changes.

{% endif %}
{% endfor %}

[tool.towncrier]
    filename = "CHANGELOG.md"
    directory = "changelog/"
    start_string = "# Changelog\n"
    issue_format = "[#{issue}](https://gitlab.com/group/project/-/issues/{issue})"
    underlines = ["", ""]
    template = ".towncrier.template.md"
    title_format = "## [{version}] - {project_date}"

[achimnol]

In towncrier 19.2.0 I get the title underline but in 21.3.0 I don't. Doesn't the trick to specify a list for underscores work any more?

19.2.0:

  21.03.19 (2021-08-23)
  ---------------------

  ### Features
  * ...

21.3.0:

  21.03.19 (2021-08-23)

  ### Features
  * ...

pyproject.toml:

[tool.towncrier]
package = "ai.backend.manager"
filename = "CHANGELOG.md"
directory = "changes/"
title_format = "{version} ({project_date})"
template = "changes/template.md"
issue_format = "([#{issue}](https://github.com/lablup/backend.ai-manager/issues/{issue}))"
underlines = ["-", "", ""]

template: link

[webknjaz]

@achimnol change it like this:

 [tool.towncrier]
  package = "ai.backend.manager"
  filename = "CHANGELOG.md"
  directory = "changes/"
- title_format = "{version} ({project_date})"
+ title_format = "# {version} ({project_date})"
  template = "changes/template.md"
  issue_format = "([#{issue}](https://github.com/lablup/backend.ai-manager/issues/{issue}))"
  underlines = ["-", "", ""]

[dgutson]

@webknjaz Is this template already merged in master? Can I output .md out of the box?

[adiroiban]

AFAI you can't output markdown out of the box.

The default configuration is for RST.

But, towncrier is flexible enough so that you can configure it to produce Markdown output.