Skip to content

markdown.md

Latest commit

 

History

History
553 lines (473 loc) · 22.1 KB

markdown.md

File metadata and controls

553 lines (473 loc) · 22.1 KB

MarkDown

What is MarkDown

Alternate Tech

Why use MarkDown

Presentation software has been refereed to as slideware jail.

Traditional slideware is hard to proofread, and tweaking text size and alignment on large decks feels like a waste of time.

... taking the contents of a single text file (markdown) and turning it into a completely acceptable and usable slide deck.

Quote from DeckDown

Online Document editing tools are also insufficient. We would not have an approval process. This would be damaging once a critical size of collaborators is reached.

We want to create a set of teaching resources that

  • Version control
    • Changelog (with rollback)
  • Facilitates collaboration
    • Comments
    • Approval process (2 people need to approve)
  • Use open industry tooling

We can use [Git] and Markdown.

If we use MarkDown to describe our content, there are system for exporting to:

  • Slideshows
    • HTML
    • Powerpoint
  • PDF's
  • Books
  • A4 Handouts
  • Websites

There are plugins for Markdown to render

Technologies

TODO: investigate mkdocs

pip3 install mkdocs
mkdocs serve

Input

  • Nanonets-OCR
    • OCR Document to Markdown (via LLM). Great for more LLM usage

Specs

  • CommonMark - A strongly defined, highly compatible specification of Markdown

Implementations

  • markdown-it - javascript renderer with plugins (used by vscode)

Upcomming?

  • ChartSS.css - accessible html/css charts with markdown support

Knowledge base

Editors

  • Desktop App
    • Marker

      • A Secure Visual Markdown Editor That is Fully Yours. Marker is an open-source, user-friendly UI for writing & editing markdown files. Everything you create lives in your filesystem.

    • RMarkdown - Introduction Video 1min
    • typora - A truly minimal markdown editor
    • qownnotes Plain-text file markdown note taking with Nextcloud integration
    • Obsidian is a powerful knowledge base that works on top of a local folder of plain text Markdown files
    • zettlr A Markdown editor for the 21st century
    • Trilium Notes is a hierarchical note taking application with focus on building large personal knowledge bases
    • MindForger
  • Browser
  • IDE Plugin/Extension
    • vscode
      • Foam
      • HackMD Extension
        • replaces the builtin preview
        • (See HackMD browser above for list of supported extras)
      • Markdown Preview Enhanced
        • extension
          • added new preview mode
          • sometimes unstable on large documents?
        • syntax
          • Superscript, line number, CriticMarks Admonition
          • enableExtendedTableSyntax in extension settings
        • Mermaid
        • flowchart.js
        • Missing
          • GraphViz
          • abc
        • PlantUML
        • Presentation Writer
        • Pandoc (output pdf, word)
        • wavedrom timing diagrams
        • ditaa - ascii art flow diagrams
        • Code Chunk - render code output into documents
        • @import 
          •   @import "your_file"
  @import "test.puml" {code_block=true class="line-numbers"}
  @import "test.md" {line_begin=2 line_end=10}
          • partial line numbers from file
          • can execute commands and include the output
  • Custom
  • mkdocs

    • Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable, in 60+ languages, for all devices.

    • This looks so beautiful!

Admonition

  • admonition
    • note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote (can add custom ones! see documentation)

https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/markdown-basics.md#admonition https://squidfunk.github.io/mkdocs-material/reference/admonitions/

!!! warning This is the admonition title This is the admonition body

Github has own flavor of admonition - called 'alerts' (thanks github) https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

Note

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goal.

Warning

Urgent info that needs immediate user attention to avoid problems.

Caution

Advises about risks or negative outcomes of certain actions.

Some after space

Flavors

Markdown is reasonably fragmented. There are a range of standards

  • GitHub Flavoured Markdown
  • GitLab Flavoured Markdown
  • CommonMark
    • An attempt to formally describe MarkDown behaviour
  • MDx

    • MDX allows you to use JSX in your markdown content. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components

Diagram Extensions Examples

  • Mermaid - Generation of diagrams and flowcharts from text in a similar manner as markdown
    • mermaid-live-editor
    • vscode markdown support
    • Mermaid to ASCII
    •   graph TB

  SubGraph1 --> SubGraph1Flow
  subgraph "SubGraph 1 Flow"
  SubGraph1Flow(SubNode 1)
  SubGraph1Flow -- Choice1 --> DoChoice1
  SubGraph1Flow -- Choice2 --> DoChoice2
  end

  subgraph "Main Graph"
  Node1[Node 1] --> Node2[Node 2]
  Node2 --> SubGraph1[Jump to SubGraph1]
  SubGraph1 --> FinalThing[Final Thing]
  end
      Loading 
    •   gantt
      title A Gantt Diagram

      section Section
      A task           :a1, 2014-01-01, 30d
      Another task     :after a1  , 20d
      section Another
      Task in sec      :2014-01-12  , 12d
      anther task      : 24d
      Loading
  • PlantUML 
    •   Bob -> Alice : hello
  Alice -> Bob : hi
    •   start

  if (Graphviz installed?) then (yes)
  :process all diagrams;
  else (no)
  :process only
  __sequence__ and __activity__ diagrams;
  endif

  stop
    • planter - Generate PlantUML ER diagram textual description from PostgreSQL tables
  • flowchart.js 
    •   Alice->Bob: Hello Bob, how are you?
  Note right of Bob: Bob thinks
  Bob-->Alice: I am good thanks!
  Note left of Alice: Alice responds
  Alice->Bob: Where have you been?

    •   st=>start: Start
  e=>end: End
  op=>operation: My Operation
  op2=>operation: lalala
  cond=>condition: Yes or No?

  st->op->op2->cond
  cond(yes)->e
  cond(no)->op2
  • graphviz
    • gallery
    • Drawing Graphs using Dot and Graphviz
    • WebGraphViz
    • create diagrams with code using graphviz
    •   digraph G {
      main -> parse -> execute;
      main -> init;
      main -> cleanup;
      execute -> make_string;
      execute -> printf
      init -> make_string;
      main -> printf;
      execute -> compare;
  }

    •   digraph G {
      node [shape = record,height=.1];
      node0[label = "<f0> |<f1> G|<f2> "];
      node1[label = "<f0> |<f1> E|<f2> "];
      node2[label = "<f0> |<f1> B|<f2> "];
      node3[label = "<f0> |<f1> F|<f2> "];
      node4[label = "<f0> |<f1> R|<f2> "];
      node5[label = "<f0> |<f1> H|<f2> "];
      node6[label = "<f0> |<f1> Y|<f2> "];
      node7[label = "<f0> |<f1> A|<f2> "];
      node8[label = "<f0> |<f1> C|<f2> "];
      "node0":f2 -> "node4":f1;
      "node0":f0 -> "node1":f1;
      "node1":f0 -> "node2":f1;
      "node1":f2 -> "node3":f1;
      "node2":f2 -> "node8":f1;
      "node2":f0 -> "node7":f1;
      "node4":f2 -> "node6":f1;
      "node4":f0 -> "node5":f1;
  }

    •   digraph hierarchy {

          nodesep=1.0 // increases the separation between nodes

          node [color=Red,fontname=Courier,shape=box] //All nodes will this shape and colour
          edge [color=Blue, style=dashed] //All the lines look like this

          Headteacher->{Deputy1 Deputy2 BusinessManager}
          Deputy1->{Teacher1 Teacher2}
          BusinessManager->ITManager
          {rank=same;ITManager Teacher1 Teacher2}  // Put them on the same level
  }
  • abc - Musical notation 
  • M:6/8
L:1/8
K:G
V:1 name="Whistle" snm="wh"  
B3 A3 | G6 | B3 A3 | G6 ||  
V:2 name="violin" snm="v"  
BdB AcA | GAG D3 | BdB AcA | GAG D6 ||  
V:3 name="Bass" snm="b" clef=bass  
D3 D3 | D6 | D3 D3 | D6 ||
  • geo 
    •   The British Museum
  • markmap
    • Mind map
  • fretboard 
    •   -oO-*-
  --o-o-
  -o-oo-
  -o-oO-
  -oo-o-
  -*O-o-
  • Markdown Preview Enhanced: Diagrams - examples
  • vega and vega-lite 
    •       {
          "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
          "description": "A simple bar chart with embedded data.",
          "data": {
              "values": [
              {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
              {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53},
              {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52}
              ]
          },
          "mark": "bar",
          "encoding": {
              "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
              "y": {"field": "b", "type": "quantitative"}
          }
      }

    •   @import "your_vega_source.json" {as="vega"}
  • More
  • CodiMD Documentation
  • Other features
  • Tenno
    • 'cell like' spreadsheet cells support in markdown to make graphs.
    • Looks really cool!

Guides

Other text systems

Unsorted

GitHub css in markdown

Alternatives?

  • excalidraw.com
    • Diagrams that look sketched by pencil
  • kroki.io - Creates diagrams from textual descriptions!
    • Live site for rendering LOADS of text to diagram notation, Vega, Graphviz, PlantUML
  • jendeley is a JSON-based document organizing software.
    • jendeley is JSON-based. You can see and edit your database quickly.
    • jendeley works locally. Your important database is owned only by you. No cloud.
    • jendeley is browser-based. You can run it anywhere node.js runs.

HTML to Markdown