Neste artigos vamos usar gulp e Markdown-it para criar o nosso próprio conversor de Markdown.
Porquê?
No nosso novo design do blog decidimos que iríamos começar a escrever os nossos artigos usando Markdown. Anteriormente usávamos um processo complexo que consistia em escrever os artigos no Google Docs, exportá-los para HTML, passá-los por um processo automático de limpeza e depois ainda tínhamos de fazer algumas correcções manuais. Em resumo, escrever novos artigos tinha-se tornado numa chatice.
Escrever directamente em HTML também não é propriamente divertido, pois rapidamente se torna muito verboso e o conteúdo começa a perder-se entre tanto markup. Por isso decidimos usar Markdown uma vez que tem uma sintaxe fácil de perceber e permite-nos focar no conteúdo.
Tínhamos na mesma a necessidade de ter controlo sobre o HTML resultante e queríamos acrescentar funcionalidades ao Markdown, por isso o Markdown-it foi a nossa salvação, visto que nos oferece controlo sobre o rendering e permite-nos criar sintaxe adicional.
Criar uma tarefa gulp para converter Markdown em HTML
Existe o plugin gulp-markdown-it que podem usar com o gulp para este propósito, mas descobri que era restritivo na forma como permitia a personalização da instância do Markdown-it e do uso de plugins, por isso decidi não fazer uso dele e usar Markdown-it directamente com gulp.
Iniciar o projecto
Primeiro iniciem o vosso projecto:
npm init
Depois adicionem as dependências necessárias:
npm install gulp --save-dev
npm install gulp-util --save-dev
npm install gulp-tap --save-dev
npm install markdown-it --save-dev
Criar o ficheiro gulp
Agora criem um gulpfile.js e incluam os requisitos:
var gulp = require('gulp');
var gutil = require('gulp-util');
var tap = require('gulp-tap');
var MarkdownIt = require('markdown-it');
Criar a tarefa gulp
Vamos criar uma tarefa gulp para converter os ficheiros Markdown para HTML.
var md = new MarkdownIt();
gulp.task('build', function() {
return gulp.src('articles/**/*.md')
.pipe(tap(markdownToHtml))
.pipe(gulp.dest('./dist'));
});
function markdownToHtml(file) {
var result = md.render(file.contents.toString());
file.contents = new Buffer(result);
file.path = gutil.replaceExtension(file.path, '.html');
return;
}
Esta tarefa vai ler todos os ficheiros md na pasta articles e convertê-los para HTML usando Markdown-it.
Criar uma tarefa gulp para olhar por mudanças
Para tornar as nossas vidas mais fáceis, vamos criar uma tarefa que está atenta a qualquer mudança nos ficheiros Markdown e corre a tarefa build automaticamente.
gulp.task('watch', function() {
gulp.watch('**/*.md', ['build']);
});
Personalizar o processo de conversão para HTML
Agora que temos o setup necessário para converter Markdown em HTML, vamos personalizar o HTML resultante. Para fazer isso podem fazer override aos renderers por omissão.
Markup das tabelas à nossa medida
Queríamos usar tabelas responsivas do Bootstrap por isso adicionamos as nossas próprias regras:
md.renderer.rules.table_open = function (tokens, idx, options, env, self) {
return '<div class="table-responsive">\n'
+ '<table class="table">\n';
};
md.renderer.rules.table_close = function (tokens, idx, options, env, self) {
return '</table>\n'
+ '</div>\n';
};
Agora todas as tabelas nos nossos ficheiros Markdown vão converter para este HTML.
Além disto, podem fazer mudanças adicionais como fazer com que todos os links abram em novas janelas ou que todas as imagens tenham a classe img-responsive, apenas para mencionar alguns exemplos.
Acrescentar ao Markdown-it usando plugins adicionais
Além de criar as nossas regras de rendering podemos também criar ou usar plugins de Markdown-it.
Aqui estão alguns plugins que usamos na nossa conversão:
- markdown-it-container: criar contentores personalizáveis
- markdown-it-regexp: construir as nossas próprias regras de substituição regexp
- markdown-it-video: incluir vídeos de YouTube e Vimeo
Alertas de Bootstrap
Usamos alertas de Bootstrap nalguns dos nossos artigos por isso queríamos uma forma fácil de expressar isso em Markdown.
Usamos o plugin markdown-it-container para criar o plugin markdown-it-alerts que faz isso mesmo.
npm install markdown-it-alerts --save-dev
var alerts = require('markdown-it-alerts');
md.use(alerts);
Vejam a página GitHub para mais informação sobre como instalar e usar o plugin.
Ícones Font Awesome
Da mesma forma, fazemos uso de Font Awesome em alguns artigos, especialmente para botões, por isso usamos o plugins markdown-it-regexp para criar o nosso próprio plugin markdown-it-fontawesome.
npm install markdown-it-fontawesome --save-dev
var fa = require('markdown-it-fontawesome');
md.use(fa);
Vejam a página GitHub para instruções.
Conclusão
Se seguiram o tutorial o vosso gulpfile.js deve estar assim:
/* global Buffer */
var gulp = require('gulp');
var gutil = require('gulp-util');
var tap = require('gulp-tap');
var MarkdownIt = require('markdown-it');
var alerts = require('markdown-it-alerts');
var fa = require('markdown-it-fontawesome');
var md = new MarkdownIt();
md.use(alerts);
md.use(fa);
md.renderer.rules.table_open = function (tokens, idx, options, env, self) {
return '<div class="table-responsive">\n'
+ '<table class="table">\n';
};
md.renderer.rules.table_close = function (tokens, idx, options, env, self) {
return '</table>\n'
+ '</div>\n';
};
gulp.task('build', function() {
return gulp.src('articles/**/*.md')
.pipe(tap(markdownToHtml))
.pipe(gulp.dest('./dist'));
});
gulp.task('watch', function() {
gulp.watch('**/*.md', ['build']);
});
function markdownToHtml(file) {
var result = md.render(file.contents.toString());
file.contents = new Buffer(result);
file.path = gutil.replaceExtension(file.path, '.html');
return;
}
Se precisarem de personalizar o processo de conversão de Markdown para HTML e estão a correr num ambiente Javascript, então recomendo que investiguem o Markdown-it. Torna-se acessível adaptar o resultado e aumentar a linguagem Markdown.