[Proposal] Introduction to Markdown and MkDocs - Build Your Technical Documentation Site with Python and Markdown

[flamanta]

Activity Name Introduction to Markdown and MkDocs - Build Your Technical Documentation Site with Python and Markdown

Short Description Participants will be introduced to the markup language Markdown via GitHub Flavored Markdown and Typora, as well as MkDocs, a static site generator that is geared towards building project documentation.

Markdown provides a more efficient and streamlined way of formatting documents. There will be a short introduction to Pandoc, a universal document converter which can convert between many markup formats.

Using Markdown together with Python, participants can learn how to create a technical documentation site using MkDocs. The site can be built and served on GitHub Pages.

Student/ Organisation/ Club organizing this Activity Cher Wei Min + (open to co-speakers)

Session intent What can participants expect?

• Introduction to Markdown

• GitHub Flavored Markdown

  • Headers, Lists, Links, Images, Code & Syntax Highlighting, Tables, Blockquotes, Inline HTML, Horizontal Line, Line Breaks

• Typora

  • Inline Math, Math Block, Auto Numbering of Math Block, Chemistry Expressions, Diagrams

• Pandoc

  • Conversion between markup formats

• MkDocs

  • Introduction
  • Theming MkDocs with Material
  • Configuring the static site
  • Create pages using Markdown
  • Building and serving the site on GitHub pages

Any prerequisite knowledge?

• Participants to have Python 3 and pip installed prior to the workshop
• Would be good to know a bit about Git/GitHub

Expected Participants TBC

Ideal Venue (If you have a specific location in mind, please let us know) Depending on the number of participants

Possible Time and Dates 9 January 2019 10am - 12pm

Speakers/Workshop facilitators Cher Wei Min + (open to co-speakers) Facilitators appreciated, the number depending on the number of signups

Logistical details Require booking of the room

POC details @flamanta

Any other details for us to know Nothing at the moment

[ryanndelion]

Hi @flamanta, a friend of mine and myself had actually planned to conduct a similar (though far more focused on LaTeX) workshop this year. We've already tested and conducted the workshop during last year's IAP so this would be the second iteration. IAP admin has also accepted our application already. Would it be possible for us to merge in some way so as to avoid crossing the streams, so to speak?

[flamanta]

Hmm I don't mind removing the LaTeX portion of the workshop to give way to your workshop.

Always great to find a fellow user of LaTeX - I wish it were used more often for typesetting documents and equations! I don't mind helping out your workshop to spread the use of LaTeX.

On the other hand, looks like I would be adding MkDocs to replace the removed LaTeX portion. Slight overlap with #10, but I'm keeping it focused on building technical documentation sites.

[ryanndelion]

Great! Yea feel free to come and join us. The workshop is being held on 20th Jan, 2000-2200. We'd be happy to let you present some parts as well. Joel gave me your contact so we can discuss there?