Markdown docs page

[rufuspollock]

As a Contributor to an Awesome page, to DataHub docs or DataHub blog I want to know how to write markdown.

As a general user of the web i want a good guide to markdown so that I can understand what it is and get started using it quickly (this is not priority but good to point out that done well this should attract general traffic).

Create a docs page on markdown (can be in misc or new data wrangling section). It should include details of how to do "datahub" markdown e.g. extra features we've added, TOCs, css classes etc.

Acceptance criteria

• [x] /docs/markdown page exist
• [x] Content is sufficient for use by someone writing a new blog post or news docs item (test briefly with someone)

Tasks

• [x] Create docs page (not test needed)

I'd recommend guide in two parts:

• [x] General intro
  • [x] What is markdown (very short)
  • [x] Short tutorial
  • [x] Examples
• [x] DataHub specific features
  • [x] How to contribute to DataHub docs?
  • [x] table of content
  • [x] template
  • [x] class="docs" - we use sass(location /public/sass/_doc.scss)
  • [x] How to write blogs on DataHub?
  • [x] table of content
  • [x] template
  • [x] class="blog" - we use sass(location /public/sass/_blog.scss)

Previous work we could reuse: http://opendatahandbook.org/contribute/

[AcckiyGerman]

Need a review https://github.com/datahq/frontend/pull/152

[AcckiyGerman]

Post-review fixes done. https://github.com/datahq/frontend/pull/152

[zelima]

@AcckiyGerman you can use Gitter channel for updates like this - works much faster

[AcckiyGerman]

The guide is created, reviewed and merged with https://github.com/datahq/frontend @rufuspollock should we proclaim this page on https://discuss.okfn.org/ so somebody from outside the team may give a feedback ?

[rufuspollock]

@AcckiyGerman a) when you report that something is done can you link to where it is live (is it live somewhere).

Re discuss.okfn.org: i don't think this is worth sharing on https://discuss.okfn.org especially.

[rufuspollock]

@anuveyatsu do we support mermaid in our docs page and/or the blog atm? If so, we should document that.

[AcckiyGerman]

@rufuspollock @anuveyatsu The markdown guide page is merged with datahq/frontend but the doc section is not yet on https://datahub.io I don't know datahub.io site update flow yet, so I didn't accent on this.

[rufuspollock]

@AcckiyGerman where is documentation of things like:

• infoboxes? (markdown extension)
• special code block e.g. cli output (datahub only)
• is there support for mermaid diagrams (?)

Also guidance on things like what is the default level for headings (e.g. you used level 3 in your markdown doc atm - which i just changed to level 2 but i think level 1 should probably be the default but i'm not sure - check with @anuveyatsu )

I'm also not clear where the guide to creating blog posts or ordinary docs went? This would have included details of .e.g

• [ ] Where to locate the files
• [ ] What frontmatter there should be
• [ ] Style and approach (e.g. a short intro paragraph for blog posts)

As general feedback I'd observe:

• Lack of attention to detail: headings with inconsistent capitalization e.g. TEXT and links as two separate headings with inconsistent and incorrect capitalization
• Images is separate from links as a section IMO
• No table of contents
• Spacing and paragraph separation (e.g. first two lines of page)
• (? - may not be needed) No links to the definition of markdown online (e.g. commonmark) or more in depth tutorials

[AcckiyGerman]

@anuveyatsu please clarify if we support this features (do I need to describe this in the article?):

• infoboxes? (markdown extension)
• special code block e.g. cli output (datahub only)
• is there support for mermaid diagrams (?)

[zelima]

@AcckiyGerman is this still issue? If yes please clarify and open it in QA and let's close this one

[AcckiyGerman]

FIXED: Instructions are on place, but we have to improve the text and add info: https://github.com/datahq/datahub-qa/issues/159