Add ability to describe an introduction text

[Undistraction]

It would be great to be able to add an Introduction to the documentation. just something to sit above the generated docs in the main column (in the default theme).

If I have a README outlining how the library should be used and full of examples, it would seem to me this should be something that I can include into the docs as an introduction. I'd love to be able to just direct to the Sassdoc from the README, but pure docs without context mean I'm going to end up boiling a lot of the docs down into the README. Being able to consolidate intro and docs would make both docs and introduction stronger.

This could be expanded to allow links from the intro to the relevant docs (perhaps just parsing out known entities from the text and adding links automagically).

[KittyGiraudel]

If we want to add an introduction text, we will probably keep it very simple: a string parsed as Markdown, injected into the DOM. I'm okay with that.

Edit: depending on the outcome of this issue, we'll move it to sassdoc-theme-default since it is strictly related to the theme at this point.

[FWeinb]

Maybe we could even allow to include a README.md right from the project root.

[Undistraction]

I think a choice of either the README or the name of a .md file would be perfect.

[KittyGiraudel]

Maybe we could even allow to include a README.md right from the project root.

I don't like this. I don't want people to write their README in some way because of SassDoc. Although we could allow either a markdown file (if string is a path), or a description as a string directly.

[FWeinb]

Adding the ability to put a path in the configuration file is fine with me. Do we move this to the default theme?

[KittyGiraudel]

@valeriangalliat, @pascalduez, okay?

[valeriangalliat]

Yep.

[pascalduez]

A path in config is fine. Let's go !

[KittyGiraudel]

Alright, so the scenario is:

• try require() on view.description;
  • if it works, put content from required file in view.description;
  • if it fails, quit (view.description is already a description).
• parse it as Markdown with sassdoc-extras;
• display it in sassdoc-theme-default on top of main container;
• write docs.

Who takes it? I can take the theme/docs stuff.

[valeriangalliat]

require is only for JavaScript or JSON files… and you want a string back. You want something like module.exports = 'description';?

Or you probably mean fs.readFile.

[KittyGiraudel]

You get the idea. If it's a path, get content, else treat content as content.