Markdown in descriptions

[valeriangalliat]

We document here that SassDoc will parse description strings as Markdown.

This is not really true; today it's the theme responsibility to parse the description as markdown.

This will make all themes require a Markdown module to decently display descriptions, and it's an overhead I think we can avoid (and we can also make it clear that the description is Markdown, and this won't be the theme's choice).

I propose we require some Markdown package in sassdoc (there's a lot of Markdown packages, I don't know which one to choose), rename the current description keys in rawDescription (to keep the original Markdown text), and put the generated HTML in description.

[KittyGiraudel]

Agreed. Who takes it?

[KittyGiraudel]

Tagged as 1.2.

[FWeinb]

I will take this! Will use marked to parse the markdown.

[FWeinb]

@valeriangalliat You might want to merge this: https://github.com/SassDoc/sassdoc/pull/118

[valeriangalliat]

Merged, I'm going to update the themes to use the pre-rendered documentation directly.

[valeriangalliat]

Hmm, looks like some other strings are parsed as Markdown in the views.

views/includes/annotations/todo.html.swig:      <li>{{ todo | markdown }}</li>
views/includes/annotations/parameters.html.swig:          <td data-label="desc">{{ parameter.description | markdown | default('&mdash;<span class="visually-hidden"> none</span>') | safe }}</td>
views/includes/annotations/author.html.swig:      <li>{{ author | markdown }}</li>
views/includes/annotations/throws.html.swig:      <li>{{ _throw | markdown }}</li>
views/includes/annotations/returns.html.swig:  <p class="sassdoc__item-description">{% if item.returns[0].description %}{{ item.returns[0].description | markdown }}{% endif %}
views/includes/partials/header.html.swig:      {{ package.description | markdown }}

I'm not sure what to do about this, maybe they should all be preprocessed as Markdown?

@HugoGiraudel, what do you think?

[KittyGiraudel]

They should.

[FWeinb]

Will fix these as well.

[KittyGiraudel]

Great. Then we'll be ready to release 1.2?

[FWeinb]

Did this directly on develop

[valeriangalliat]

Nice, so todo, author, _throw are all HTML strings? I'm updating the themes.

[FWeinb]

todo
parameters
author
throws
returns
package.description

These are all HTML.

[valeriangalliat]

Okay, I upgraded sassdoc-theme-{light,dark}.

[valeriangalliat]

There's a problem... the title is wrapped with a <p> but we display it in a header tag...

[FWeinb]

Which title?

[valeriangalliat]

Oops my bad, wait a minut... :(

[valeriangalliat]

The theme was not updated, I think because I installed with npm install and it was not in the package.json, false alert.