Este tutorial (AINDA INCOMPLETO, EM DRAFT) apresenta como criar um site estático, em JavaScript, utilizando o Metalsmith, um dos vários geradores de sites estáticos existentes no mercado.
Os seguintes assuntos são explorados:
-
Organização de uma estrutura de diretórios para o projeto;
-
Utilização do NodeJS e do Metalsmith;
-
Utilização do Git para o versionamento dos fontes;
-
Utilização do Vim com plugins provendo features para syntax highlighting e code completion para linguagens como JavaScript, JSON, Jade e Markdown, dentre outras;
-
Escrita de páginas utilizando a linguagem Markdown;
-
Escrita de templates utilizando a linguagem Jade;
-
Criação de sites apresentando conteúdos em diferentes línguas;
Nesta versão, este tutorial expande, adapta e executa, passo a passo, numa VM Linux, os comandos apresentados, de forma bastante prática prática e assertiva, nestes dois outro tutoriais:
Para que você possa se aprofundar ainda mais nos assuntos cobertos aqui, é recomendada a leitura desses materiais. Você pode fazer isso antes ou depois de seguir este tutorial, fica a teu critério.
1. Criando o projeto
Inicie o projeto com os seguintes comandos:
mkdir metalsmith-test && cd $_
cat > README.md <<'EOF'
# Metalsmith Test
Aplicação desenvolvida seguindo o [tutorial-metalsmith](https://paulojeronimo.github.io/tutorial-metalsmith/) criado pelo [Paulo Jerônimo](https://github.com/paulojeronimo).
EOF
date > TIMESTAMP
npm init
Abaixo são apresentadas as respostas que dou para os questionamentos feitos pelo comando acima.
Em tuas respostas, utilize o teu nome para o campo author e deixe as outras respostas iguais.
|
This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg> --save` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. name: (metalsmith-test) version: (1.0.0) description: Metalsmith test entry point: (index.js) test command: git repository: . keywords: metalsmith javascript author: Paulo Jerônimo license: (ISC)
Verifique se o conteúdo do teu arquivo package.json
é semelhante a este.
Faça o teu primeiro git commit:
git init
git add .
git commit -m 'Criado o projeto'
Você receberá um erro na execução do comando
|
2. Adicionando o Metalsmith
Adicione o metalsmith ao package.json
e crie um novo arquivo HTML com os comandos abaixo:
npm install --save metalsmith
mkdir content && touch content/index.html
Observe as mudanças no repositório (git status
).
Crie o arquivo index.js
com o comando abaixo:
cat > index.js <<'EOF'
var path = require('path');
var metalsmith = require('metalsmith');
metalsmith(__dirname)
.source('content')
.destination('dist')
.build(function (err) {
if (err) { console.error(err); }
});
EOF
Observe as mudanças na estrutura de diretórios do repositório:
tree -L 1
node index.js
find dist/
git status
Crie o arquivo .gitignore
com o comando abaixo:
cat > .gitignore <<'EOF'
dist
node_modules
EOF
Faça o teu segundo commit:
git status
git add .
git commit -m 'Adicionado o uso do Metalsmith'
Verifique o log do repositório:
git log --name-status
3. Fazendo o uso de arquivos Markdown
Renomeie e o arquivo index.html
para index.md
e altere o seu conteúdo com os seguintes comandos:
git mv content/index.html content/index.md
cat > content/index.md <<'EOF'
---
title: Home
---
My collection of **recipes**.
EOF
Adicione o pacote metalsmith-markdown
:
npm install --save metalsmith-markdown
Clone o código desse tutorial e adicione seu diretório ao .gitignore
. Estamos fazendo isso para poder utilizar alguns arquivos de seu repositório.
git clone https://github.com/paulojeronimo/tutorial-metalsmith
echo tutorial-metalsmith >> .gitignore
O conteúdo apresenta, no formato diff, as mudanças que você precisará fazer no index.js
:
as linhas com um "+" na frente representam adições realizadas. |
diff --git a/index.js b/index.js
index eeb354b..6dac41a 100644
--- a/index.js
+++ b/index.js
@@ -1,10 +1,12 @@
var path = require('path');
var metalsmith = require('metalsmith');
+var markdown = require('metalsmith-markdown');
metalsmith(__dirname)
.source('content')
.destination('dist')
+ .use(markdown())
.build(function (err) {
if (err) { console.error(err); }
});
Você pode fazer essas alterações "na mão", alterando o arquivo, se quiser. Ou, você pode simplificar tua vida e executar o seguinte comando:
git apply tutorial-metalsmith/patches/index.js.1
Você observará as mudanças através do comando git difftool
. Antes, porém, faça as seguintes configurações:
git config --global diff.tool vimdiff
git config --global --add difftool.prompt false
Agora, veja as diferenças:
git difftool
Execute o comando abaixo e veja o arquivo (index.html
) que será gerado a partir do index.md
:
node index.js
cat dist/index.html
Faça o teu terceiro git commit:
git status
git add .
git commit -m 'Feito o uso de arquivos Markdown'
4. Disponibilizando arquivos estáticos (imagens, CSS, etc)
Adicione o uso do pacote metalsmith-assets
:
npm install --save metalsmith-assets
Crie o diretório assets/css
e o arquivo styles.css
dentro dele. Em seguida veja a estrutura montada.
mkdir -p assets/css && touch $_/styles.css
tree assets/
Para fazer uso de assets, mudanças precisarão ser realizadas no index.js
, conforme o conteúdo abaixo:
diff --git a/index.js b/index.js
index 6dac41a..6f0288f 100644
--- a/index.js
+++ b/index.js
@@ -2,11 +2,15 @@ var path = require('path');
var metalsmith = require('metalsmith');
var markdown = require('metalsmith-markdown');
+var assets = require('metalsmith-assets');
metalsmith(__dirname)
.source('content')
.destination('dist')
.use(markdown())
+ .use(assets({
+ source: 'assets'
+ }))
.build(function (err) {
if (err) { console.error(err); }
});
Altere o index.js
executando o comando a seguir:
git apply tutorial-metalsmith/patches/index.js.2
Verifique a mudança, rode novamente o index.js
, e veja a estrutura construída:
cat index.js
node $_
tree dist/
Faça o teu quarto git commit:
git status
git add .
git commit -m 'Disponibilizado arquivos estáticos'
5. Desenvolvendo o uso de layouts
npm install --save jade metalsmith-layouts
mkdir -p layouts && cat > layouts/default.jade <<EOF
doctype html
head
title Cookbook - #{title}
meta(charset='utf-8')
link(rel='stylesheet', href='/css/styles.css')
body
header
h1 Cookbook
main: article
h1= title
!= contents
EOF
cat tutorial-metalsmith/patches/index.js.3
git apply !$
node index.js
cat dist/index.html
git status
git add .
git commit -m 'Desenvolvido o uso de layouts'
6. Suportando o uso de múltiplas línguas
git mv content/index.md content/index_en.md
cat > content/index_es.md <<'EOF'
---
title: Inicio
---
Mi colección de **recetas**.
EOF
npm install --save metalsmith-multi-language
git apply tutorial-metalsmith/patches/index.js.4
cat index.js
node $_
tree dist/
git status
git add .
git commit -m 'Suportado o uso de múltiplas línguas 1/2'
git apply tutorial-metalsmith/patches/layouts/default.jade.1
cat layouts/default.jade
node index.js
npm install -g http-server
(cd dist/; http-server -p 4000)
Abra a URL http://localhost:4000 e teste a aplicação. Ao terminar teu teste, pressione um Ctrl+C para encerrar o servidor e continuar os próximos comandos.
git status
git commit -am 'Suportado o uso de múltiplas línguas 2/2'
7. Inserindo a localização nas URLs
npm install --save metalsmith-permalinks
mkdir content/recipes
cat > content/recipes/tortilla_en.md <<'EOF'
---
title: Spanish omelette
---
Ingredients:
- 2 potatoes
- 3 eggs
- 1 onion
- Olive oil
- Salt
EOF
cat > content/recipes/tortilla_es.md <<'EOF'
---
title: Tortilla de patatas
---
Ingredientes:
- 2 patatas
- 3 huevos
- 1 cebolla
- Aceite de oliva
- Sal
EOF
git apply tutorial-metalsmith/patches/index.js.5
git apply tutorial-metalsmith/patches/content/index_en.md.1
node index.js
(cd dist/; http-server -p 4000)
Abra a URL http://localhost:4000/en/spanish-omelette/ e teste a aplicação. Ao terminar teu teste, pressione um Ctrl+C para encerrar o servidor e continuar os próximos comandos.
git status
git add .
git commit -m 'Inserida a localização nas URLs'
8. Traduzindo o layout
npm install --save metalsmith-i18n
mkdir -p locales
cat > locales/en.json <<'EOF'
{
"Cookbook": "Cookbook",
"Also available in": "Also available in",
"es": "castellano"
}
EOF
cat > locales/es.json <<'EOF'
{
"Cookbook": "Recetario",
"Also available in": "Disponible también en",
"en": "English"
}
EOF
git apply tutorial-metalsmith/patches/index.js.6
git apply tutorial-metalsmith/patches/layouts/default.jade.2
node index.js
(cd dist/; http-server -p 4000)
Abra a URL http://localhost:4000/en/spanish-omelette/ e teste a aplicação. Ao terminar teu teste, pressione um Ctrl+C para encerrar o servidor e continuar os próximos comandos.
git status
git add .
git commit -m 'Traduzido o layout'
9. Traduzindo as URLs
npm install --save metalsmith-collections
git apply tutorial-metalsmith/patches/index.js.7
node index.js
tree dist/
(cd dist/; http-server -p 4000)
Abra a URL http://localhost:4000/en/recipes/spanish-omelette/ e teste a aplicação. Ao terminar teu teste, pressione um Ctrl+C para encerrar o servidor e continuar os próximos comandos.
git status
git add .
git commit -m 'Traduzidas as URLs'
10. Gerando um índice localizado
git apply tutorial-metalsmith/patches/layouts/default.jade.3
cat > layouts/home.jade <<'EOF'
extends ./default.jade
block extra
h2= __('Recipes')
ul
each recipe in collections[`recipes_${locale}`]
li: a(href=`/${recipe.path}`)= recipe.title
EOF
git apply tutorial-metalsmith/patches/content/index_en.md.2
node index.js
git status
sed -i 's/\(: "\)Recipes/\1Recetas/g' locales/es.json
cat $_
git status
git add .
git commit -m 'Gerado um índice localizado'
11. Apresentando uma história de sucesso
Parabéns! Você concluiu um bom trabalho! Execute o comando git a seguir para ver toda a tua história de sucesso:
git log --pretty=format:'* %s %Cgreen(%cr)'