agon-markdown

Posts Tagged ‘markdown’

Sublime Text下使用markdown的环境搭建和配置

December 15th, 2016, Posted by: agon   

试了一堆markdown线上或客户端编写工具,感觉都不顺手,最后还是决定用sublime text,搭建环境最终效果为,sublime下编辑markdown,并在浏览器端显示最终效果。浏览器里显示效果最好的是Markdown Preview,各种特性完美转换,基本不需要单独配置,推荐新手用。1

前提及环境

只要会Package Control安装插件就行了,系统环境为windows10,sublime text版本为3。

插件安装

Markdown Editing的安装

Sublime下写markdown必备插件,主要功能是为Markdown and MultiMarkdown提供inline formatting(源文件内显示加粗、标题、引用等风格)、关键字的自动补齐和闭合,另外还有一些有用的的快捷方式(例如control+1为标题1),这些为markdown的编写省去不少时间。2

Markdown Preview的安装

通过Markdown Preview的安装我们可以在浏览器里看到最终显示效果,或者导出html到文件所在文件夹(ctrl+b),还可以通过配置自己css模板,看到在自己网站下浏览的最终效果。还有一个优点就是转出的html比较干净整洁,和自己网站上的css好搭。3这个插件有几个好处:支持的扩展全;支持MultiMarkdown的扩展语法,例如在生成的html元素里添加自定义的id或者class;同时也有几个比较好用的命令。4
自定义快捷建:如果我们想要直接在浏览器中预览效果的话,可以自定义快捷键:点击Preferences -> Key Bindings,添加以下代码:


    "keys": ["alt+m"], "command": "markdown_preview", "args": { "target": "browser"},

alt+m在浏览器里查看浏览最终效果。

  • 一些简单的配置:设置语法高亮和mathjax支持
    同样点击Preferences ->Package Settings->Markdown Preview->Setting-user

    /*
    需要数学公式的这个改为true
    */
    "enable_mathjax": true,
    
    /* 
     如果需要看代码高亮效果这个改为true,但是生成的html code很乱,如果你需要转出干净的html,发布网站上有自定的高亮模板,直接改为false
    */
    "enable_highlight": false,
    

Live Reload的安装和设置

这个插件的作用是,当你保存markdown文件的时候,浏览器会跟着更新效果,注意是 先保存文件。如果保存后浏览器不会自动更新,需要再设置一下,按快捷键Control+Shift+P,输入livereload,会看到LiveReload:enable/disable plugins,选择enable-Simple Reload,需要注意的是,每次都关闭打开sublime都要重复上述enable操作。

源文件内语法高亮

需要个漂亮的主题敲起字来才心情舒畅,默认的markdown editing的主题实在是难看,并且代码段也不会高亮,看起来很不直观,顺便推荐一个主题插件,__Monokai Extended Package__,Package Control搜索’Monokai’安装。然后依次点开下图的三个配置文件:
设置主题
全都添加Monokai Extended的主题,并把你的文件mardown文件后缀都改成mmd。

    "color_scheme": "Packages/Monokai Extended/Monokai Extended.tmTheme",
    "line_numbers": true
}

高亮效果如下图:
高亮效果

实时预览方案

经过上面的简单安装和配置你就可以愉快的在SublimeText下写东西了,如果你嫌手动保存实在麻烦,或者文章太长需要实时看一下效果,可以尝试一下下面两个方案。

OmniMarkupPreviewer

这个插件不像上面那个需要手动再选择,实时预览,我之所以没用这个,是因为好些扩展没有Markdown Preview支持的全,比如tasklist格式转成html代码不好看,部分扩展在配置里打开时会报错比如tstrikeout(开启会报错),还有就是转出的html代码比较整洁。可以参考脚注里的链接。另外如果以后熟悉markdown了就不用老看最终效果,很少会实时预览了。需要配置的请看脚注5

markmon

这个插件需要额外安装node.js、pandoc,利用pandoc生成的html在浏览器里实现实时预览,效果还不错,有评价pandoc才是markdown界最高逼格的,但是在默认命令里生成的html里,我需要的几个功能,解析出的结果都不太满意,例如页脚部分引用没有解释成超链接,不支持添加自定义元素的id和class,可能是我还没学pandoc,命令不会使。对pndoc比较熟悉的人,这个应该是最棒的方案。安装方法参考下面两个链接:
点这里,按流程装完在配置文件里加上"executable": "markmon.cmd"就可以了。

  1. InstallPandoc
  2. Install Node.js.
  3. cmd下运行命令npm install -g markmon
  4. Install SublimeText插件markmon.
  5. 在用户配置文件Preferences->Package Settings->Markmon->Settings,填上这个{ "executable": "markmon.cmd", },这个是windows用户需要添加的,否则会报错
  6. 重启SublimeText 并运行工具点击Tools->Markmon->Launch,打开markmon
  7. 配置自己的需求,默认用的域名是127.0.0.1,你可以配置成自己想要的域名,任何访问这个地址的都可以实时预览,还是在第5步用户配置文件里的逗号后面添加上下面下面的markmon配置:
        //开启的端口,你自己服务器设置的多少就开哪个
        "port": 3002,
        //pandoc的路径,安装的时候已经添加到环境变量里了,如果你的没有,添加pandoc安装路径在这里
        "pandoc_path": "",
        //markmon好像不像makdown preview那么多自定义,其实他使用pandoc来实现的,前提是你得学会pandoc的相关命令,从而实现加载自己的html模板、css、js和相关扩展,
        "command": "pandoc -t HTML5 --mathjax",
        //这个应该是加载自己的stylesheet吧,没尝试
        "stylesheet": null,
        //这个会在pandoc生成命令里添加project位置,就是本地文件相对路径的那个文件夹
        "projectdir": null
    

有具体需要的,可以学习pandoc的相关命令。
效果如下图:
markmon实时效果预览

进阶配置

上面的安装设置做完之后,已经可以开始写了。等慢慢熟悉了markdown,有进一步需求可以再进一步配置,满足自己的需求。详细的配置和源码可以去 发布页面

Markdown Preview的设置

自定义生成的html文件路径

修改用户配置文件里的’path_tempfile’,为你自定义的文件见,方便查找生成的html文件,以及后期加载自定义css、js、本地路径图片,例如"path_tempfile": "./",就可以在mark文件所在文件夹下,生成对应的html文件,访问相对路径下的加载文件。

添加自定义的css和模板

加载自己的css和html模板,以期转出的html和自己网站风格兼容,同时也可以添加方便的侧边栏,方便预览:
自定义出题
涉及到下面的几个变量,在菜单里打开用户配置文件,把默认文件里的几个配置粘进来:
打开用户配置和默认配置文件
修改下面几个选项

/*
    这个是加载默认的css,如果自定义的话,把它放进注释里里面    
    "css": ["default"],
*/


//生成的临时html文件位置
"path_tempfile": "E:\\我的模板",
/*
   这里定义html模板的位置,html模板很简单,就是一个html文件,哪里放上{{ BODY }}这个标签,哪里就会被文章对应html替换。
   {{ HEAD }} 这个标签意义不大,替换默认生成的head,既然自定义,肯定在自己的html文件里写自己的head。
   后面的路径换成你自己的模板文件路径,注意如果模板里使用相对路径的js和css文件,保持html_template和path_tempfile在同一个文件
*/
"html_template": "E:\\我的模板\\模板.html",
//跳过默认的模板,加载自定义模板改为true
"skip_default_stylesheet": true,
//导出干净的html源文件,没有自定义的额为的html和css标记,部分扩展增加的标记可能会出问题。还是自己写个脚本来复制带扩展的html。
`"html_simple": false`

到此我们就完成了自定义html模板了。

关于扩展的设置

这个插件的好处是扩展全,但是有些扩展可能是我们不需要的,举个例子HeaderAnchor,他会网h标签里插入一大堆东西,如果你自己网站没有对应的css,实现相应功能,就没必要实现这个扩展。除了不含HeaderAnchor,把所有扩展都写出来了,你可以根据自己需要来增减。

    "enabled_extensions": ["extra", "toc", "meta", "sane_lists", "smarty", "wikilinks","magiclink", "delete", "tasklist", "githubemoji",  "superfences", "nl2br"],

    "guess_language": false,

Markdown Editing的设置

Markdown Editing有三种格式的设置文件,对应markdown的三个版本,其中GTM为githubmarkdown的缩写,那两个分别是标准版,一个扩展版。7通过对后缀名的识别,来判断应用哪个配置文件。除了上面高亮代码部分把主题添加到用户配置里,还要把你想配对的后缀添加到配置里,推荐个比较暴力的方法,因为MultiMarkdown的支持的扩展最多,把所有markdown文件后缀都识别成MultiMarkdown格式,打开MultiMarkdown配置添加下面的代码,同时删除其他用户配置里的extensions。

"extensions":
    [
        "mmd",
        "mdown",
        "txt",
        "md",
    ],

Markdown Editing的常用快捷键,及自定义常用快捷键

  • alt+b粗体;alt+i斜体;
  • ctl+1~6对应H1~H6标题;
  • mdc+Tab添加代码段,按tab切换位置
  • mdl+Tab添加链接;mdi+Tab添加图片
  • Win+Ctrl+v,创建格式为[]()的链接,更快的流程是,复制链接,然后按这个快捷键,链接已经在括号里了,光标留在方括号写文字描述。
  • Ctrl+Alt+g,引用间跳转,鼠标放在引用的方括号里,按快捷键,在文末和文中的位置互相跳转。
  • ……

tips

其他需要补充的常用的小窍门

常见问题

  • 无法更改markdown editing安装后的默认主题:6默认非常难看,一片灰白,就是在菜单栏和用户配置文件
    里,添加上Monokai Extended的主题,也还是没有改变,除了markdown文件的主题以外,别的文件格式都正常。可能是markdown文件后缀没有被认成正确的格式,没有对应markdown editing的主题。首先确保在上面安装主题的步骤里,每个对应的配置里,都是Monokai的主题,,然后在显示不正常的markdown文件下,点View -> Syntax -> open all with current extension as,选择Markdown Editing -> MultiMarkdown这样就和你sublime里设置的主题一样了。如果还不一样,在Preferences -> Settings-Syntax Specific,配置文件里添加如下代码:

    {
        "color_scheme": "Packages/Monokai Extended/Monokai Extended.tmTheme",
        "line_numbers": true,
    }
    

    如果你做了上述一切还是不行,尝试下改个markdown文件后缀,改成’.mmd’,这个后缀主题支持的最好,文件内代码高亮都很清楚一致。

资源教程整理

Page 1 of 11