search

jeffwils / grails-spring-security-saml

Grails Spring Security SAML2.0 Plugin for Grails 3
8 stars 25 forks source link

Split README.md into README.md and USAGE.md #42

Closed irstevenson closed 6 years ago

irstevenson commented 6 years ago

Due to the way that plugins.grails.org displays the README.md on a the main page of the plugin (see http://plugins.grails.org/plugin/jeffwils/spring-security-saml), we need to be careful what's in README.md. For example, the table of configuration properties in the current README.md does not render on plugins.grails.org - and as a result, makes the quality of the plugin look questionable.

As a result, I believe it'd be best to split README.md at the 'Configuration' heading, and place everything from there down in a new USAGE.md. Then, have a link in README.md to USAGE.md. (I believe that link will then also be accessible from plugins.grails.org.)

This is similar to what I see other plugins doing - although if you look at Spring Security Core plugin, they're a bit more sever.

valentingoebel commented 6 years ago

We have an official project site where we should put the extended documentation. If you click on the "Documentation" link on the plugin site you will get redirected to that page. The big question is how do we modify that project site. I'm pretty sure that it's just showing the current README.MD.

How do we split it so that github shows the full docs but the grails plugin site only shows the readme?

valentingoebel commented 6 years ago

@jeffwils Do you know how we can modify the project site?

valentingoebel commented 6 years ago

For reference: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/

valentingoebel commented 6 years ago

https://github.com/jeffwils/grails-spring-security-saml/pull/46 has solved this issue.