Markdown

Markdown is short-form HTML. There are several flavours with different featuresets.

TODO:

These are old, bad, ugly. fixme

Notes

markdown syntax

Parsers

ruby kramdown

ruby redcarpet

c sundown

c upskirt

ruby github flavoured markdown

Workflow

WARNING:

This is really out of date

Overview

Personal Script automatically generates .html files every time a .md file is saved in vim.

### Pipeline
vim
  Markdown-Syntax
  autolaunch convert-markdown.py on save *.md

python2
  pip
  pygments
  markdown2
  markdown
  py-markdown-ditaa

python-markdown.py
  pers: markdown-converter.py
  pers: markdownToc.py

chromium
  Tincr (extension reloads page when files change CSS+html)
  To use:
   open page in chromium
   Menu > Tools > Developer Tools
   Click Tincr Tab
   Done. Next save should automatically reload

    ~OR~

firefox
  autoReload (reloads page when files change CSS+html)

python setup

### install markdown2.py
pip install markdown2               #for (fork)markdown 2  (no longer using)
pip install markdown                #for (official) markdown
pip install pygments                #for syntax highlighting support


### Official Use:
python2 markdown2.py myFile.md > myFile.html



### Personal Use (markdown2-converter.py)
# creates html of same name in same dir, using variable DEFAULT_CSS_PATH for css
python2 markdown2-converter.py myFile.md
python2 markdown-converter.py myFile.md

# can also specify html name, location, css file
python2 markdown2-converter.py myFile.md C:/path/to/style.css C:/myFile.html
python2 markdown-converter.py myFile.md C:/path/to/style.css C:/myFile.html


# use any variety of paths
python2 markdown2-converter.py myFile.md C:/file.md C:/something/style.css D:/web/web.html
python2 markdown-converter.py myFile.md C:/file.md C:/something/style.css D:/web/web.html

vim setup

:PluginInstall Markdown-Syntax

### .vimrc
au BuffRead,BufNewFile *.md set filetype=markdown


if has("unix")
   autocmd BufWritePost *.md silent !$progs/python/general/markdown/markdown2-converter.py <afile>
elseif has("win32")
   autocmd BufWritePost *.md silent ! P:\Python27\Scripts\python.exe \%progs\%/python/general/markdown/markdown-converter.py <afile> silent
endif


Plugin 'Markdown-syntax'

Firefox

### Install autoReload extension (reloads automatically when files are updated)
firefox file.md

#(nothing else required, page reloads entirely by itself!)

MathJax

Mathjax was a pain to setup last time, and it was a paint to sync. I also deleted it once by mistake, and it took a fair amount of reading to get it working again, so I'll document it's use specifically for use with markdown here:

####### Using Mathjax CDN (requires online) ##########
### HTML (already coded in markdown-converter.py):
<!--mathjax-->
	<script type="text/x-mathjax-config">
		MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
	</script>
	<script type="text/javascript"
		src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
	</script>
</head>

### Use in markdown:
single '$'s or '\(' and  '\)'        -------      Inline LaTeX (single line)
anything between  '$$'s              -------      Displayed LaTeX (standard)




## Inline Code Example:
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are

## Displayed Code Example:
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are

ditaa

the ditaa package for python-markdown is not included in pip, and requires a manual installation.

Install Java: Portable version available (see jportable). Portable or not, must add bin directory to %PATH%

can test with:

java -version

Install ditaa: I have ditaa installed in my python site-packages directory. Only planning to use with python-markdown.

Test with:

java -jar ditaa0.9.jar --help

Next, install script: Find markdown's extension location:

## Typically P:\Python27\lib\site-packages\markdown
python2 -c "import markdown; print markdown.__path__[0]"

download and install mdx_ditaa.py to

site-packages/markdown

or above location

CSS Styles

Note that all colours (including the syntax highlighting called on by pygments) must be present in the CSS stylesheet or they will not appear.

Colors

http://www.color-hex.com/color-wheel/

Fonts

http://www.w3schools.com/cssref/css_websafe_fonts.asp

Syntax Highlighting themes:

https://github.com/richleland/pygments-css

General Appearance themes:

https://github.com/jasonm23/markdown-css-themes #Click on sample html pages, links at top to view more than just 3 listed