Configure Sections using markdown files in folders and front-matter

[pke]

I know we can configure sections via a custom config.

But wouldn't it be cool if the sections could be generated simply by [index|section].md files in src folders using YAML front matter (https://github.com/matthewwithanm/markdown-with-front-matter-loader)?

---
section: Name of the section
---

# Section description

This would further simplify the configuration. What you think?

[n1313]

I personally would not use the word "simply" to describe a setup with non-standard markdown syntax and an extra dependency which does exactly the same as one line in the config, but that's just me.

I see that front-matter is something that comes with Jekyll, which converts "plain text into static websites and blogs". Is it related to react and components in some way?

[okonet]

Front matter is just a convention that many are using. I'm not sure how much value it will bring in this context, though. @pke can you give us some use cases for that?

[sapegin]

Yeah, I’d like to see some use cases where it actually simplify configuration. For me it brings more questions: ordering for example?

What we can do is ignore front matters in markdown files and then generating sections config would be a few lines of code and up to the user.

[n1313]

While this extra markup could definitely be ignored by RSG, it will remain in README.md files and "pollute" their "native" display in GitHub/Stash. I personally quite enjoy having my code and my examples being written in a simple, no-special-markup-required way. But, I guess, if this is an optional feature then I don't have to use it if I don't want to, so that's not a big deal.

…

Sent from my iPhone

On 30 Mar 2017, at 18:15, Artem Sapegin ***@***.***> wrote: Yeah, I’d like to see some use cases where it actually simplify configuration. For me it brings more questions: ordering for example? What we can do is ignore front matters in markdown files and then generating sections config would be a few lines of code and up to the user. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[okonet]

GitHub actually can present front matter very nicely as a table. See https://github.com/okonet/colorsnapper-website/blob/master/_pages/faq.md for example so this isn't an issue IMO.

[sapegin]

It can be optional in a way that you don’t have to use front matters. So Styleguidist will just ignore them but actual reading front matters and generation of a config object would be up to the user.

[PDXIII]

I would love to be able to use front matter.

[okonet]

Yeah the more I think about it the more I like the idea. I might work on a PR for that since I might need it for some of my projects

[okonet]

My use case is a customization of particular examples. So what I’d be looking for is an ability to pass props to the example renderer component or to the example components themselves (via context?)

[PDXIII]

I would like to have it to be able to give components an approval status, which could be passed to the header. Or add an author etc.

[MrHavard]

My team recently developed a script to build the sections hierarchy based off of html comment+yaml. The syntax is super simple, keeps the components portable, renders clean in github, and provides a good amount of control.

For example, all the developer has to do is open the readme.md and add an html comment to the top with the name of the current component and what parent it belongs to. If there's no parent then we assume that the readme is defining the root.

We were thinking about contributing this back to styleguidist as an additional config option once we refine it a little more. We've only been using it about a month on a project with 140 components, but so far it seems to be working fine.

[okonet]

That sounds great but I’d suggest to use frontmatter instead of HTML comments. Possible?

[MrHavard]

That sounds great but I’d suggest to use frontmatter instead of HTML comments. Possible?

We're using gray-matter which uses frontmatter but also allows us to define custom delimiters, which we specified as html comments that wrap the yaml. We were going to use frontmatter directly but having a table pop up in the top of our readme's in github wasn't something we liked.

Example

<!---
title: Accordion Group
parent: Accordion
--->