grunt-docs
grunt-docs copied to clipboard
gruntjs
Create a proper "Documentation" index page
Currently the "Documentation" link on Grunt's website header links to the same location as "Getting Started".
It would be more practical to instead have the documentation link to a "documentation overview" landing page. Also, removing duplicated URLs is a good idea.
Feel free to comment to this issue if you have ideas on what a "Documentation Overview" landing page should look like.
I can take of this task if available but I'd like also to have some guidance. Is there anything that you definitely want to show on this page?
@AurelioDeRosa, I see you asked for some guidance, sorry I missed your call!
I saw this GitHub one, for a little inspiration, but it sounds like you've already made one!
Thank you for the suggestion. I've followed your hint to create the page.
So far the introductory wording is fantastic; we just need to have a complete index of doc pages as well—like a "Contents" page for quick reference, and very much similar to the existing side-bars of the site.
Thank you for the shout out @JKAussieSkater. In regard of your point to improve the page, do you want to add the content of the sidebar in the Documentation page as well?
Yeah! Maybe split it up into a two column grid just to see how it feels.
Do we have the possibility to split in columns using markdown? The only way without classes and html markup I can think of is to use a table which will lead to poor semantic.
I don't think Git flavoured markdown (which can do tables) is supported by the Jade parser . . . I could be wrong. But ultimately we need a good visual layout for an index, so we've got to do what we've got to do. HTML is the way to go.
Looks like there is table support recently at least tho, I've used this tool: http://www.tablesgenerator.com/markdown_tables
| Tables | Are | Cool |
|---|---|---|
| col 1 is | left-aligned | $1600 |
| col 2 is | centered | $12 |
| col 3 is | right-aligned | $1 |
OBTW you guys are kicking butt!
I have mixed sentiments on this matter. On one side I'd like to stick with Markdown and not starting the Markdown/HTML mix which will result in a mess. On the other hand, tables for semantic suck. If I'm forced to pick one, I'd rather go for Markdown/HTML mix though.
In regard of the classes to use, I've seen that the website uses Bootstrap v2. So, we should have a structure like:
<div class="row-fluid">
<div class="span6">
Content here
</div>
<div class="span6">
Content here
</div>
</div>
Any further comment or are we good to go?
P.S.: Thank you @dmethvin!
That's a sick generator @dmethvin!
@AurelioDeRosa, Let's go with the Bootstrap option.
I've submitted a PR based on our discussion. Hopefully it matches the expectations.
@vladikoff, how might we go about using HTML in our *.md files? It doesn't seem to be compatible with the Jade parser on the stage server. Here's a screenshot:
Edit: This is regarding Documentation.md
Perhaps there is an escape HTML entities in place? For instance, in Handlebars instead of using {{variable}} you have to write {{{variable}}}.
Looks like vladikoff is busy this week, @shama, do you have any ideas how we can embed HTML in the Jade/Markdown files?
escape it as in show the html?
<div>Like this</div>
Is the markdown processing different you are talking about different than the gh-pages? If it's not, then I would think you could use kramdown syntax and the code highlighting would be rouge. If this were the case, you can apply css to markdown items yada yada.
@JKAussieSkater I'm not too familiar but the docs are built with gollum correct? So depending on the tags, using HTML in the markdown should work: https://github.com/gollum/gollum/wiki/Security#page-sanitization. As for Jade, they have syntax for raw HTML: http://jade-lang.com/reference/plain-text/
Is there any update for the HTML code of the documentation that was removed for the release?