├── .gitignore ├── MANIFEST.in ├── README.md ├── descriptions.rst ├── mdtogh ├── __init__.py ├── command.py ├── github_renderer.py ├── offline_renderer.py ├── renderer.py ├── settings.py ├── templates │ ├── base.html │ ├── content.html │ ├── index.html │ └── toc.html ├── toc.py ├── transform.py └── util.py ├── requirements.txt └── setup.py /.gitignore: -------------------------------------------------------------------------------- 1 | # Environment files 2 | *.so 3 | *.py[cod] 4 | 5 | # OS-specific files 6 | .DS_Store 7 | Desktop.ini 8 | Thumbs.db 9 | 10 | #vim backup 11 | *~ 12 | .*.swp 13 | 14 | #easysetup 15 | build/* 16 | dist/* 17 | mdtogh.egg-info/* 18 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include descriptions.rst 2 | include README.md 3 | include requirements.txt 4 | 5 | graft mdtogh/templates 6 | global-exclude *~ 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | #Markdown to Github Html 2 | 3 | ##Motivation 4 | 5 | Basically, You may want to convert md files into Html looks exactly like github does. 6 | 7 | Maybe you would try [pandoc](http://johnmacfarlane.net/pandoc/index.html), but html it generates looks **not** very well(~~Just my own opinion~~). 8 | 9 | So, I start writing this small tool, inspired by [grip](https://github.com/joeyespo/grip) 10 | 11 | ##Features 12 | 13 | mdtogh can **convert** your md files into html files like github does with features belows: 14 | 15 | * toc support 16 | * custom toc(use one file to be toc) 17 | * index.html for your book 18 | * next/prev files link 19 | * file regexp to select your md files 20 | * fix relative link(ie. `` => ``) 21 | * custom template 22 | * offline renderer 23 | * proxy support(respect https\_proxy environment variable) 24 | * cache support 25 | 26 | ##demo 27 | 28 | 29 | I've generate a book written by julycoding: [The-Art-Of-Programming-By-July](https://github.com/julycoding/The-Art-Of-Programming-By-July). 30 | 31 | Demo link: [taop.marchtea.com](http://taop.marchtea.com) 32 | 33 | You can check on that. 34 | 35 | 36 | ##Installation 37 | 38 | From [pypi](https://pypi.python.org/pypi) 39 | 40 | $ pip install mdtogh 41 | 42 | Also, you can clone repo & install with setup.py. 43 | 44 | $ git clone https://github.com/marchtea/md_to_github_html.git 45 | $ cd md_to_github_html 46 | $ python setup.py install 47 | 48 | **Maybe you will need add `sudo`** 49 | 50 | ##Usage 51 | 52 | Generate one or more files: 53 | 54 | $ cd mdfiles 55 | $ mdtogh 01.md 02.md 03.md 56 | 57 | Generate all md files in current directory: 58 | 59 | $ cd mdfiles 60 | $ mdtogh 61 | 62 | Generate md files in other directory: 63 | 64 | $ mdtogh ../mdfiles 65 | 66 | Generate files with file reg support: 67 | 68 | $ cd mdfiles 69 | $ mdtogh --file_reg='^\d.+\.md' 70 | 71 | Generate files with toc & toc_depth support: 72 | 73 | $ cd mdfiles 74 | $ mdtogh --toc --toc_depth=2 --file_reg='^\d.+\.md' 75 | 76 | Generate files with additional book info. 77 | 78 | $ cd mdfiles 79 | $ mdtogh --toc --book='book.json' 80 | 81 | The format of `book.json` is given below. 82 | 83 | Generate files with custom template: 84 | 85 | $ cd mdfiles 86 | $ mdtogh --templates=path_to_templates 01.md 87 | 88 | The rules for `templates` is given below. 89 | 90 | Generate files with custom toc file: 91 | 92 | $ cd mdfiles 93 | $ mdtogh --toc --toc_file=Readme.md --file_reg='^\d.+\.md' 94 | 95 | Offline rendering: 96 | 97 | $ cd mdfiles 98 | $ mdtogh --offline 01.0.md 99 | 100 | **Recommanded** options to `generate book`: 101 | 102 | $ mdtogh --css --toc --book='book.json' --file_reg='your reg exp' 103 | 104 | **Recommanded** options to generate `several files`: 105 | 106 | $ mdtogh 01.md 02.md 107 | 108 | For more options: 109 | 110 | mdtogh -h 111 | 112 | ##Something You May Notice 113 | 114 | As to generate files exactly like github does, the easiest way is to use [api](http://developer.github.com/v3/markdown/) if offers. But it has its own [limits](http://developer.github.com/v3/#rate-limiting). 115 | 116 | * 60 for anonymous requests an hour 117 | * 5000 for requests using `Basic Authentication` an hour 118 | 119 | So, you may using `--user` & `--pass` options 120 | 121 | $ mdtogh --user='your_github_username' --pass='your login password' 122 | 123 | Your info is sent through `https` which is safe. `mdtogh` will not save any of it. 124 | 125 | 126 | ##book.json 127 | 128 | ``` 129 | { 130 | "title": "Demo book", 131 | "description": "This is a book.", 132 | "coverimage": "demo.jpg" 133 | } 134 | ``` 135 | 136 | ##Custom Templates Support 137 | 138 | mdtogh now support custom templates. You can use --templates to specific where to locate templates. You should give at least three files belows: 139 | 140 | * content.html 141 | * toc.html 142 | * index.html 143 | 144 | mdtogh use [jinja2](https://github.com/mitsuhiko/jinja2) as template engine. 145 | 146 | For tutorial of template writing, please check [this](http://jinja.pocoo.org/docs/) 147 | 148 | ###content.html 149 | 150 | `content.html` is used for generate standalone html file with things like `head`, `body` **after** content of md file is rendered by `github` or `offline renderer`. 151 | 152 | mdtogh will pass several parameters to `content.html` which you can use: 153 | 154 | * filetitle *#booktitle in book.json`* 155 | * content *#contents after render by `github` or `offline renderer`* 156 | * toc *#not support yet* 157 | * needtoc *#whether toc is needed* 158 | * prevfile *#link to prevfile. only used when `--toc` is set* 159 | * nextfile *#link to nextfile. only used when `--toc`is set* 160 | 161 | ###toc.html 162 | 163 | `toc.html` is used for generate table of content which will be used later in index.html. So, you don't need add `` or `` tag. 164 | 165 | 166 | Parameters passed to `toc.html`. 167 | 168 | * tocs 169 | * toc_depth 170 | 171 | ####tocs 172 | tocs is a list of headers. It's set like : 173 | 174 | ``` 175 | [ 176 | ['h1', 'top header', 'headerlink'], 177 | ['h2', 'sub header', 'header link'], 178 | .... 179 | ] 180 | ``` 181 | 182 | ####toc_depth 183 | 184 | toc_depth is set by user. It refers the maxium depth of header. It's an integer value. ie. 185 | 186 | ``` 187 | 2 188 | ``` 189 | 190 | ###index.html 191 | 192 | `index.html` is used for generate index.html for book. 193 | 194 | Parameters passed to `index.html`: 195 | 196 | * booktitle *#title in book.json* 197 | * coverimage *#coverimage in book.json* 198 | * description *#description in book.json* 199 | * toc *#toc rendered with toc.html* 200 | * custom_toc *#whether use custom_toc. custom_toc is rendered like normal md file* 201 | 202 | 203 | ##TODO 204 | `mdtogh` is still on developing. 205 | 206 | Features are developing or will be add later. 207 | 208 | * support recursive options. 209 | * add toc in content.html 210 | 211 | ##Contibuting 212 | Any **help** will be **appreciated**. 213 | 214 | * open issue if you find any questions 215 | * complete tasks in TODO list 216 | * add features you like 217 | * feel free to open pull request 218 | 219 | ##Links 220 | 221 | * [grip](https://github.com/joeyespo/grip) 222 | * [github markdown api](http://developer.github.com/v3/markdown/) 223 | 224 | ##Change Log 225 | 226 | * 2014/4/30 0.0.9 add option: --timeout. set timeout for requests. add cache support. now it will skip file which is not changed. 227 | * 2014/3/12 0.0.8 add option: --offline. offline rendering is supported. 228 | * 2014/3/11 0.0.7 add option: --toc_file. user can specific one file as toc. relative link will be resolved automatically. 229 | * 2014/3/6 0.0.6 add option: --encoding for offline renderer, fix relative link, add support for custom template 230 | * 2014/3/5 0.0.5 add MANIFEST.in, fix pacakge wrapped by `setup.py`. Fix css link not include while rendering after first downloading css files 231 | * 2014/3/4 0.0.3 fix error leads by unicode filename 232 | * 2014/3/3 0.0.2 add --toc_depth support, fix get_html_name bug 233 | * 2014/3/1 0.0.1 first release 234 | 235 | ##Thanks 236 | Special thanks to [grip](https://github.com/joeyespo/grip). Without its excellent work, this tool can't be done. 237 | 238 | -------------------------------------------------------------------------------- /descriptions.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | Markdown to Github Html 3 | ========================== 4 | 5 | Motivation 6 | =============== 7 | 8 | Basically, You may want to convert md files into Html looks exactly like github does. 9 | 10 | Maybe you would try `pandoc`_, but html it generates looks **not** very well. 11 | 12 | So, I start writing this small tool, inspired by `grip`_ 13 | 14 | Features 15 | ================= 16 | 17 | mdtogh can **convert** your md files into html files like github does with features belows: 18 | 19 | - toc support 20 | - custom toc(use one file to be toc) 21 | - index.html for your book 22 | - next/prev files link 23 | - file regexp to select your md files 24 | - fix relative link(ie. `` => ``) 25 | - custom template 26 | - offline renderer 27 | - proxy support(respect https_proxy environment variable) 28 | - cache support 29 | 30 | demo 31 | ================= 32 | 33 | I've generate a book written by julycoding: `The-Art-Of-Programming-By-July`_. 34 | 35 | Demo link: `taop.marchtea.com`_ 36 | 37 | You can check on that. 38 | 39 | 40 | Installation 41 | ============== 42 | 43 | From `pypi`_ 44 | 45 | .. code-block:: bash 46 | 47 | $ pip install mdtogh 48 | 49 | Also, you can clone repo & install with setup.py. 50 | 51 | .. code-block:: bash 52 | 53 | $ git clone https://github.com/marchtea/md_to_github_html.git 54 | $ cd md_to_github_html 55 | $ python setup.py install 56 | 57 | **Maybe you will need add sudo** 58 | 59 | Usage 60 | ================== 61 | 62 | Generate one or more files 63 | 64 | .. code-block:: bash 65 | 66 | $ cd mdfiles 67 | $ mdtogh 01.md 02.md 03.md 68 | 69 | Generate all md files in current directory 70 | 71 | .. code-block:: bash 72 | 73 | $ cd mdfiles 74 | $ mdtogh 75 | 76 | Generate md files in other directory 77 | 78 | .. code-block:: bash 79 | 80 | $ mdtogh ../mdfiles 81 | 82 | Generate files with file reg support 83 | 84 | .. code-block:: bash 85 | 86 | $ cd mdfiles 87 | $ mdtogh --file_reg='^\d.+\.md' 88 | 89 | Generate files with toc & toc_depth support 90 | 91 | .. code-block:: bash 92 | 93 | $ cd mdfiles 94 | $ mdtogh --toc --toc_depth=2 --file_reg='^\d.+\.md' 95 | 96 | Generate files with additional book info 97 | 98 | .. code-block:: bash 99 | 100 | $ cd mdfiles 101 | $ mdtogh --toc --book='book.json' 102 | 103 | The format of book.json is given below. 104 | 105 | Generate files with custom template 106 | 107 | .. code-block:: bash 108 | 109 | $ cd mdfiles 110 | $ mdtogh --templates=path_to_templates 01.md 111 | 112 | The rules for templates is given below. 113 | 114 | Generate files with custom toc file 115 | 116 | .. code-block:: bash 117 | 118 | $ cd mdfiles 119 | $ mdtogh --toc --toc_file=Readme.md --file_reg='^\d.+\.md' 120 | 121 | Offline rendering: 122 | 123 | .. code-block:: bash 124 | 125 | $ cd mdfiles 126 | $ mdtogh --offline 01.0.md 127 | 128 | **Recommanded** options to generate book 129 | 130 | .. code-block:: bash 131 | 132 | $ mdtogh --css --toc --book='book.json' --file_reg='your reg exp' 133 | 134 | **Recommanded** options to generate several files 135 | 136 | .. code-block:: bash 137 | 138 | $ mdtogh 01.md 02.md 139 | 140 | For more options 141 | 142 | .. code-block:: bash 143 | 144 | mdtogh -h 145 | 146 | Something You May Notice 147 | ================================= 148 | 149 | As to generate files exactly like github does, the easiest way is to use 150 | `api`_ if offers. But it has its own `limits`_. 151 | 152 | - 60 for anonymous requests an hour 153 | - 5000 for requests using Basic Authentication an hour 154 | 155 | So, you may using --user & --pass options 156 | 157 | .. code-block:: bash 158 | 159 | $ mdtogh --user='your_github_username' --pass='your login password' 160 | 161 | Your info are sended through https which is safe. mdtogh will not save any of it. 162 | 163 | 164 | book.json 165 | ======================== 166 | 167 | .. code-block:: javascript 168 | 169 | { 170 | "title": "Demo book", 171 | "description": "This is a book.", 172 | "coverimage": "demo.jpg" 173 | } 174 | 175 | Custom Templates Support 176 | ======================== 177 | 178 | mdtogh now support custom templates. You can use --templates to specific where to locate templates. You should give at least three files belows: 179 | 180 | - content.html 181 | - toc.html 182 | - index.html 183 | 184 | mdtogh use `jinja2`_ as template engine. 185 | 186 | For tutorial of template writing, please check `jinja doc`_ 187 | 188 | - content.html 189 | 190 | content.html is used for generate standalone html file with things like head, body **after** content of md file is rendered by github or offline renderer. 191 | 192 | mdtogh will pass several parameters to content.html which you can use: 193 | 194 | - filetitle *#booktitle in book.json`* 195 | - content *#contents after render by `github` or `offline renderer`* 196 | - toc *#not support yet* 197 | - needtoc *#whether toc is needed* 198 | - prevfile *#link to prevfile. only used when `--toc` is set* 199 | - nextfile *#link to nextfile. only used when `--toc`is set* 200 | 201 | 202 | toc.html 203 | 204 | toc.html is used for generate table of content which will be used later in index.html. So, you don't need add html or body tag. 205 | 206 | 207 | Parameters passed to toc.html. 208 | 209 | - tocs 210 | - toc_depth 211 | 212 | tocs 213 | 214 | tocs is a list of headers. It's set like 215 | 216 | .. code-block:: javascript 217 | 218 | [ 219 | ['h1', 'top header', 'headerlink'], 220 | ['h2', 'sub header', 'header link'], 221 | .... 222 | ] 223 | 224 | toc_depth 225 | 226 | toc_depth is set by user. It refers the maxium depth of header. It's an integer value. ie. 227 | 228 | .. code-block:: javascript 229 | 230 | 2 231 | 232 | index.html 233 | 234 | index.html is used for generate index.html for book. 235 | 236 | Parameters passed to toc.html: 237 | 238 | - booktitle *#title in book.json* 239 | - coverimage *#coverimage in book.json* 240 | - description *#description in book.json* 241 | - toc *#toc rendered with toc.html* 242 | - custom_toc *#whether use custom_toc. custom_toc is rendered like normal md file* 243 | 244 | TODO 245 | =================== 246 | mdtogh is still on developing. 247 | 248 | Features are developing or will be add later. 249 | 250 | - support recursive options. 251 | - add toc in content.html 252 | 253 | Contibuting 254 | =============== 255 | 256 | Any **help** will be **appreciated**. 257 | 258 | - open issues if you find any questions 259 | - complete one in TODO list 260 | - add features you like 261 | - feel free to open pull request 262 | 263 | Links 264 | ===================== 265 | 266 | - `Github repo`_ 267 | - `grip`_ 268 | - `github markdown api`_ 269 | 270 | Change Log 271 | ===================== 272 | 273 | - 2014/4/30 0.0.9 add option: --timeout. set timeout for requests. add cache support. now it will skip file which is not changed. 274 | - 2014/3/12 0.0.8 add option: --offline. offline rendering is supported. 275 | - 2014/3/11 0.0.7 add option: --toc_file. user can specific one file as toc. relative link will be resolved automatically. 276 | - 2014/3/6 0.0.6 add option: --encoding for offline renderer, fix relative link, add support for custom template 277 | - 2014/3/5 0.0.5 add MANIFEST.in, fix pacakge wrapped by setup.py. Fix css link not include while rendering after first downloading css files 278 | - 2014/3/4 0.0.3 fix error leads by unicode filename 279 | - 2014/3/3 0.0.2 add --toc_depth support, fix get_html_name bug 280 | - 2014/3/1 0.0.1 first release 281 | 282 | Thanks 283 | ========== 284 | 285 | Special thanks to `grip`_. Without its excellent work, this tool can't be done. 286 | 287 | .. _limits: http://developer.github.com/v3/#rate-limiting 288 | .. _api: http://developer.github.com/v3/markdown/ 289 | .. _github markdown api: http://developer.github.com/v3/markdown/ 290 | .. _pypi: https://pypi.python.org/pypi 291 | .. _grip: https://github.com/joeyespo/grip 292 | .. _pandoc: http://johnmacfarlane.net/pandoc/index.html 293 | .. _The-Art-Of-Programming-By-July: https://github.com/julycoding/The-Art-Of-Programming-By-July 294 | .. _taop.marchtea.com: http://taop.marchtea.com 295 | .. _Github repo: http://github.com/marchtea/mdtogh 296 | .. _jinja2: https://github.com/mitsuhiko/jinja2 297 | .. _jinja doc: http://jinja.pocoo.org/docs/ 298 | -------------------------------------------------------------------------------- /mdtogh/__init__.py: -------------------------------------------------------------------------------- 1 | """\ 2 | Markdown to Github 3 | ---- 4 | 5 | Render local files exactly like github does. 6 | 7 | :copyright: (c) 2014 by Summer. 8 | """ 9 | 10 | __version__ = '0.0.9' 11 | 12 | from . import command 13 | from .transform import transform 14 | -------------------------------------------------------------------------------- /mdtogh/command.py: -------------------------------------------------------------------------------- 1 | """\ 2 | mdtogh.command 3 | ------------------- 4 | 5 | Implements the command-line interface for md to github. 6 | 7 | 8 | Usage: 9 | mdtogh [options] [] ... 10 | mdtogh -h | --help 11 | mdtogh --version 12 | 13 | Where: 14 | is a file or a directory to render, [default: '.'] 15 | 16 | Options: 17 | --templates= path of templates, it should contains all three files: content.html, toc.html, index.html 18 | --cache_path= path to store style file cache, default to current directory 19 | --system_css using system wide css. 20 | --css when NOT set, css contents are generate into html 21 | --abscss link css with absolute path, use only with --css is set 22 | --gfm Use GitHub-Flavored Markdown, e.g. comments or issues 23 | --context= The repository context, only taken into account with --gfm 24 | --user= GitHub username for API authentication 25 | --pass= GitHub password for API authentication 26 | --toc Generate table of contents 27 | --toc_depth= Max toc depth, default to 2 28 | --toc_file= You can specific a file to be toc(Just incase you have one) 29 | --book= Generate toc with book info, only used when --toc is set 30 | --offline Use offline renderer 31 | --encoding= encode for file, use only when --offline is set 32 | --refresh clear cached styles & refetch them 33 | --file_reg= when path is a directory, using reg_exp to get file, this reg_exp must obey python's rules 34 | if not set, mdtogh will get all files end with .md or .markdown, Notice: this is case-insensitive. 35 | --timeout=