Integrate with living style guide

Abby805 commented 5 years ago

Implementation details TBD.

Consider KSS or similar
May be useful to reference previous work done on https://bitbucket.org/bixal/elsalvador/src/living-style-guide/web/themes/custom/elsa_bixal/

allgood2386 commented 5 years ago

this will also be helpful I think https://packagist.org/packages/bixal/style_guide_response @gerardo-gov might have a better idea of it's state

mejiaj commented 5 years ago

Is there any preference on how it's generated? For example, inline-comments vs a dedicated file (could be markdown).

-Update-

Styleguide: Stylemark

Pros

Stylemark is one of the few styleguides that are still being semi-actively maintained. The setup, for the most part is:

un-opinionated
easy to get started
modern looking
Themable

Cons

I've added Stylemark on branch master+issue-3, but it seems it's incompatible with sass-lint because of the required Stylemark formatting. It causes sass-lint to throw errors like this:

[10:19:27] Error in plugin "sass-lint"
Message:
    1 errors detected in global/_forms.scss
Details:
    domainEmitter: [object Object]
    domainThrown: false

The only found solution to getting rid of that error is downgrading the version of sass-lint, which I am strongly against.

I'm content in ignoring the issue until sass-lint gets updated. But I'd like to hear other thoughts/opinions. I've also written down some alternatives below that didn't quite make the list for one reason or another.

Alternatives

https://github.com/styledown/styledown (old)
https://github.com/jonathantneal/mdcss
https://github.com/EightMedia/styleguide.js (needs theming)
https://github.com/nopr/sassdown
https://warpspire.com/kss/styleguides/ (old, not lightweight)

Abby805 commented 5 years ago

Echoing offline discussion: I'd rather not disable sass linting, but I agree with @mejiaj about not downgrading the version either. James is going to look a bit into Stylemark's option to use external markdown files as templates instead of SASS comments (which is a slightly higher LOE, but may provide a cleaner separation of concerns anyway).

g3r4 commented 5 years ago

I think we can explore using (https://packagist.org/packages/bixal/style_guide_response)

That is the one we used for the ELSA (El Salvador) project it should be somewhat sane, however we coded this a while ago and might need a little bit of work.

Since I am seeing that a lot of those style guide projects have some issues, I think we can use what we did with that module and improve it a bit.

Let me know if you all agree this would be a good option and I can take some time to take a look at it and remember what we did there.

Abby805 commented 5 years ago

@g3r4 - Am I right in understanding that bixal/style_guide_response makes the rendered style guide accessible within the site's normal URL structure? That sounds really useful, and shouldn't be dependent upon any particular style guide generator, right?

It looks like the ELSA project used https://github.com/morishitter/postcss-style-guide for the style guide itself, which hasn't been updated in several years (though it probably made sense when that project was written). I'm inclined to support @mejiaj 's recommendation to use a style guide library that's being actively maintained.

mejiaj commented 5 years ago

PR submitted https://github.com/Bixal/achiote/pull/7

@g3r4 , right now it generates it to styleguide/dist/index.html it would be great to be able to set the directory in style_guide_response, but we can also use another plugin to rename the file to styleguide/dist/style-guide.html.

Bixal / achiote