HackMD
  • Beta
    Beta  Get a sneak peek of HackMD’s new design
    Turn on the feature preview and give us feedback.
    Go → Got it
      • Create new note
      • Create a note from template
    • Beta  Get a sneak peek of HackMD’s new design
      Beta  Get a sneak peek of HackMD’s new design
      Turn on the feature preview and give us feedback.
      Go → Got it
      • Sharing Link copied
      • /edit
      • View mode
        • Edit mode
        • View mode
        • Book mode
        • Slide mode
        Edit mode View mode Book mode Slide mode
      • Note Permission
      • Read
        • Only me
        • Signed-in users
        • Everyone
        Only me Signed-in users Everyone
      • Write
        • Only me
        • Signed-in users
        • Everyone
        Only me Signed-in users Everyone
      • More (Comment, Invitee)
      • Publishing
        Please check the box to agree to the Community Guidelines.
        Everyone on the web can find and read all notes of this public team.
        After the note is published, everyone on the web can find and read this note.
        See all published notes on profile page.
      • Commenting Enable
        Disabled Forbidden Owners Signed-in users Everyone
      • Permission
        • Forbidden
        • Owners
        • Signed-in users
        • Everyone
      • Invitee
      • No invitee
      • Options
      • Versions and GitHub Sync
      • Transfer ownership
      • Delete this note
      • Template
      • Save as template
      • Insert from template
      • Export
      • Dropbox
      • Google Drive Export to Google Drive
      • Gist
      • Import
      • Dropbox
      • Google Drive Import from Google Drive
      • Gist
      • Clipboard
      • Download
      • Markdown
      • HTML
      • Raw HTML
    Menu Sharing Create Help
    Create Create new note Create a note from template
    Menu
    Options
    Versions and GitHub Sync Transfer ownership Delete this note
    Export
    Dropbox Google Drive Export to Google Drive Gist
    Import
    Dropbox Google Drive Import from Google Drive Gist Clipboard
    Download
    Markdown HTML Raw HTML
    Back
    Sharing
    Sharing Link copied
    /edit
    View mode
    • Edit mode
    • View mode
    • Book mode
    • Slide mode
    Edit mode View mode Book mode Slide mode
    Note Permission
    Read
    Only me
    • Only me
    • Signed-in users
    • Everyone
    Only me Signed-in users Everyone
    Write
    Only me
    • Only me
    • Signed-in users
    • Everyone
    Only me Signed-in users Everyone
    More (Comment, Invitee)
    Publishing
    Please check the box to agree to the Community Guidelines.
    Everyone on the web can find and read all notes of this public team.
    After the note is published, everyone on the web can find and read this note.
    See all published notes on profile page.
    More (Comment, Invitee)
    Commenting Enable
    Disabled Forbidden Owners Signed-in users Everyone
    Permission
    Owners
    • Forbidden
    • Owners
    • Signed-in users
    • Everyone
    Invitee
    No invitee
       owned this note    owned this note      
    Published Linked with GitHub
    Like BookmarkBookmarked
    Subscribed
    • Any changes
      Be notified of any changes
    • Mention me
      Be notified of mention me
    • Unsubscribe
    Subscribe
    ## Markdown discovery In August 2018 a work colleague sent me some notes in the form of a .md file and corresponding PDF. I looked up <a href="https://fileinfo.com/extension/md">fileinfo</a> and learnt that this was Markdown. As a long time note taker in ASCII file the idea of formatting text simply so it could be later converted to HTML was very appealing, I could not believe I had not heard of it before or thought about it myself. When doing web pages I've always striven to have readable HTML - e.g. save a word file to html and look at the source to see an example of unreadable html. ## Syntax highlighting I immediately started using Markdown and reading about it myself. It was released by [John Gruber ](https://daringfireball.net/projects/markdown/) in 2004. I have used [EdditPad](https://www.editpadlite.com/) as my text editor for many years and I am used to opening files in it and they being syntax colour highlighted, e.g. for HTML, XML, JSON. My .md file were not syntax highlighted. EditPad has a [Syntax Coloring Scheme Editor](https://www.editpadpro.com/manual.html#filetypecscsedit) which people can use to create schemes and then share with other EditPad users by [uploading](https://www.editpadpro.com/cscs.html). But surely someone had done it already? I found a syntax highlighter on GitHub for EditPad, which seemed to work. But better still, I then found out that I had not updated to the latest EditPad as Markdown support was added in EditPad Pro 7.6.2 :-). It turns out the GitHub scheme is faulty. ## What is Markdown though? After a week of so of note taking with Markdown I figured it would be nice to see some output, have a table of contents and see all my pages together. Reading the [EditPad Pro 7.6.2 release notes](https://www.editpadpro.com/releasenotes.html) I was wondering about how to print to HTML and I even emailed support asking where I go to convert the .md file to a PDF? The ever patient Jan Goyvaerts explained to me that an editor like EditPad allows you to edit Markdown but it cannot render markdown as a formatted page. He added that this is similar to allowing you to edit HTML, but not being able to render the HTML as a formatted page. I could not believe I had not made the same conclusion! *Update Feb 2019*. [Visual Code](https://code.visualstudio.com/) does a fantastic job of previewing markdown. I've been using Markdown for over 4 months now and only in writing this article today did I learnt that Markdown is also a tool for converting the Markdown syntax to HTML! If I had taken in all of Jan’s email at the start he diligently explained that another application is needed to convert Markdown to PDF, or one can use the [original Markdown.pl Perl script](https://daringfireball.net/projects/markdown/) to convert Markdown to HTML and print that to PDF with your browser. Indeed, In Gruber’s readme, he says: > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). > Thus, "Markdown" is two things: a plain text markup syntax, and a software tool, written in Perl, that converts the plain text markup to HTML The download contains the pearl script, Markdown.pl, and refers to (Gruber's webpage)[http://daringfireball.net/projects/markdown] for the Markdown syntax. ## Converting Markdown to HTML I wanted to render the documents to generate HTML from multiple files, i.e. create a table of contents of pages and join them together outputting HTML. I discovered [Pandoc](https://pandoc.org/) and learnt you could use it to convert Markdown to html. It works well. pandoc *.md > markdown_book.html will merge all the files in the execution directory alphabetically prior to translating to HTML. Of course there's no auto generated table of contents. The manual does suggest you need to do pandoc -f markdown -t html5 -o myfile.html myfile.md but the more simple options works fine: pandoc myfile.md > myfile.html There is one gotcha however, the markdown file must first be in UTF-8, otherwise you get the error: pandoc: Cannot decode byte '\x92': Data.Text.Internal.Encoding.decodeUtf8: Invalid UTF-8 stream My editor (EditPad) had a real handy option to convert the text encoding to Unicode UTF-8, you can then resave the file. Alternatively you can convert the file from the PowerShell command line using the not very convenient: Get-Content .\myfile.md | Set-Content -Encoding utf8 myfile.utf-8.md Another gotcha for me is to remember to leave blank lines around indented code blocks, like the above, otherwise they will not indent! ## Markdown alternatives Researching more for options I found out that that (arguably) the [main Markdown alternatives](http://hyperpolyglot.org/lightweight-markup) are a massive rabbit hole and there's loads others too...[Creole](http://www.wikicreole.org/wiki/CheatSheet), [Textile](https://github.com/textile/php-textile) briefly had me excited... You can find blog posts on all the alternatives which extol their virtues, e.g. [asciidoc: an awesome markdown alternative](https://ivoanjo.me/blog/2017/10/22/asciidoc-an-awesome-markdown-alternative/). Then, you will also find "When comparing reStructuredText vs AsciiDoc, the Slant community recommends reStructuredText for most people". Another religious topic methinks! ## DokuWiki It started to really annoy me that there are so many variants of markup syntax all over the place! I started to think about [DokuWiki](https://www.dokuwiki.org) which I have used as a personal wiki since the mid naughties, it has it's own [markup syntax](https://www.dokuwiki.org/wiki:syntax) too. Could I not use DokuWiki syntax independent of the wiki? On the DokuWiki forum I learnt that this was [not possible](https://forum.dokuwiki.org/thread/16418). I found out about [Zim](http://www.zim-wiki.org/), most of Zim's syntax is DokuWiki syntax, and you can use it like a notebook and also export to a joined up website. I also learnt that Pandoc had support for DokuWiki but it was for output only, that is Pandoc can convert to DokuWiki syntax. It turned out there was an [open issue](https://github.com/jgm/pandoc/issues/1792) for the last 4 years to add Pandoc DokuWiki reader support, I added a comment with my use case. Coincidentally, the issue was closed today and will be included in the next Pandoc release :-) ## Markdown cheatsheet The Markdown alternatives lead me back to, well Markdown, though I hope to remain curious. I guess there is a reason Markdown has not been updated since 2004. As [Gruber says](https://daringfireball.net/projects/markdown/syntax#html) > Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text. I wanted a typical one page cheat sheet I could hang on my wall. None of the [cheat sheets](https://www.markdownguide.org/cheat-sheet) were ideal for me, they were too long or missing information like how to deal with nested lists\code blocks. The one I settled on is from [Ahred code](http://code.ahren.org/markdown-cheatsheet). ## Alternative to HTML generation For wiki pages and clog posts there are options to generating output from your Markdown. Confluence has it's own [markup sytax](https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html) of course though is [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG) now. There are a [number of ways](https://community.atlassian.com/t5/Confluence-questions/Import-markdown-into-Confluence/qaq-p/211797) to use Markdown inc a confluence page but they simplest is via Insert > Markup & select Markdown. If you have your own [Wordpress.org](https://en.support.wordpress.com/com-vs-org/) site there is a plugin WP-Markdown that allows you to use paste your MarkDown into a new post but it is not maintained and I would not recommend it. Instead I use Pandoc and paste the HTML. I used Markdown for [this post](http://reducekeystrokes.com/2018/08/24/is-there-life-after-a-smartphone/) in August 2018 as well as this page itself. [Have a look](https://hackmd.io/hJmVTBW0SMW8KmoN3kNtUA) at the Markdown used for this page in side-by-side view with the HTML. ## Trying Markdown Gruber has a [sandbox](https://daringfireball.net/projects/markdown/dingus) where you can try Markdown and you can [use Pandoc online](http://pandoc.org/try/) to render it to HTML. Alternatively there are loads of online Markdown editors such as [stackedit.io](https://stackedit.io/) In-browser Markdown editor & [Markdowner](https://markdowner.github.io/]. I like the side by side editors where you can see the markup in one pan and the HTML output in another, [hackmd.io](https://hackmd.io) works great for this and each edit also gets it's own URL.

    Import from clipboard

    Advanced permission required

    Your current role can only read. Ask the system administrator to acquire write and comment permission.

    This team is disabled

    Sorry, this team is disabled. You can't edit this note.

    This note is locked

    Sorry, only owner can edit this note.

    Reach the limit

    Sorry, you've reached the max length this note can be.
    Please reduce the content or divide it to more notes, thank you!

    Import from Gist

    Import from Snippet

    or

    Export to Snippet

    Are you sure?

    Do you really want to delete this note?
    All users will lost their connection.

    Create a note from template

    Create a note from template

    Oops...
    This template is not available.


    Upgrade

    All
    • All
    • Team
    No template found.

    Create custom template


    Upgrade

    Delete template

    Do you really want to delete this template?

    This page need refresh

    You have an incompatible client version.
    Refresh to update.
    New version available!
    See releases notes here
    Refresh to enjoy new features.
    Your user state has changed.
    Refresh to load new user state.

    Sign in

    Forgot password

    or

    By clicking below, you agree to our terms of service.

    Sign in via Facebook Sign in via Twitter Sign in via GitHub Sign in via Dropbox

    New to HackMD? Sign up

    Help

    • English
    • 中文
    • Français
    • Deutsch
    • 日本語
    • Español
    • Català
    • Ελληνικά
    • Português
    • italiano
    • Türkçe
    • Русский
    • Nederlands
    • hrvatski jezik
    • język polski
    • Українська
    • हिन्दी
    • svenska
    • Esperanto
    • dansk

    Documents

    Tutorials

    Book Mode Tutorial

    Slide Mode Tutorial

    YAML Metadata

    Contacts

    Facebook

    Twitter

    Feedback

    Send us email

    Resources

    Releases

    Pricing

    Blog

    Policy

    Terms

    Privacy

    Cheatsheet

    Syntax Example Reference
    # Header Header 基本排版
    - Unordered List
    • Unordered List
    1. Ordered List
    1. Ordered List
    - [ ] Todo List
    • Todo List
    > Blockquote
    Blockquote
    **Bold font** Bold font
    *Italics font* Italics font
    ~~Strikethrough~~ Strikethrough
    19^th^ 19th
    H~2~O H2O
    ++Inserted text++ Inserted text
    ==Marked text== Marked text
    [link text](https:// "title") Link
    ![image alt](https:// "title") Image
    `Code` Code 在筆記中貼入程式碼
    ```javascript
    var i = 0;
    ```
    var i = 0;
    :smile: :smile: Emoji list
    {%youtube youtube_id %} Externals
    $L^aT_eX$ LaTeX
    :::info
    This is a alert area.
    :::

    This is a alert area.

    Versions

    Versions and GitHub Sync

    Sign in to link this note to GitHub Learn more
    This note is not linked with GitHub Learn more
     
    Add badge Pull Push GitHub Link Settings
    Upgrade now

    Version named by    

    More Less
    • Edit
    • Delete

    Note content is identical to the latest version.
    Compare with
      Choose a version
      No search result
      Version not found

    Feedback

    Submission failed, please try again

    Thanks for your support.

    On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?

    Please give us some advice and help us improve HackMD.

     

    Thanks for your feedback

    Remove version name

    Do you want to remove this version name and description?

    Transfer ownership

    Transfer to
      Warning: is a public team. If you transfer note to this team, everyone on the web can find and read this note.

        Link with GitHub

        Please authorize HackMD on GitHub

        Please sign in to GitHub and install the HackMD app on your GitHub repo. Learn more

         Sign in to GitHub

        HackMD links with GitHub through a GitHub App. You can choose which repo to install our App.

        Push the note to GitHub Push to GitHub Pull a file from GitHub

          Authorize again
         

        Choose which file to push to

        Select repo
        Refresh Authorize more repos
        Select branch
        Select file
        Select branch
        Choose version(s) to push
        • Save a new version and push
        • Choose from existing versions
        Available push count

        Upgrade

        Pull from GitHub

         
        File from GitHub
        File from HackMD

        GitHub Link Settings

        File linked

        Linked by
        File path
        Last synced branch
        Available push count

        Upgrade

        Danger Zone

        Unlink
        You will no longer receive notification when GitHub file changes after unlink.

        Syncing

        Push failed

        Push successfully