Faça o desenvolvimento HTML de várias páginas sugar menos com o Pug

Inspirado por uma história verdadeira

Foto de Jorge Zapata em Unsplash

Vamos fazer uma viagem …

Imagine que você está na lista de chamadas de uma agência freelance em uma cidade de sua escolha. Agora digamos que você receba uma mensagem legal em sua caixa de entrada. Você abre a mensagem e parece bem normal.

Temos uma necessidade imediata de um desenvolvedor para começar hoje.

Sendo uma pessoa que gosta de comer comida para sobreviver, você digita algumas informações e se aplica.

Cinco minutos depois de apertar o botão de envio, você recebe uma ligação. 10 minutos depois disso, você está recebendo o acesso ao servidor.

Escusado será dizer que você está em um prazo. Esse prazo é até o final do dia.

Você abre os arquivos HTML e olha para eles… horrorizados.

O código está em todo lugar, confuso e desorganizado. Para não mencionar, você tem que fazer ajustes no cabeçalho e rodapé … em cinco páginas diferentes.

A primeira coisa que você faz é executá-lo através de Prettify (Graças a Deus por Prettify). Isso limpou, mas há mais alguns problemas. Este é um site HTML estático, o que significa que todas as alterações feitas no material global (cabeçalho, rodapé e assim por diante), você terá que copiar em todos os arquivos. Oh meu.

O que você vai fazer???

Simples, você vai agitar um arquivo Webpack para lidar com a parte ruim de escrever HTML, e você vai fazer isso rapidamente.

Aqui está o que você precisa estar familiarizado:

  • Javascript! (por causa do Webpack)
  • HTML! (porque é disso que a internet é feita)
  • CSS! (porque quem gosta de coisas feias?)
  • pug! (porque esse é o ponto deste artigo!)
  • npm (porque é Deus)
  • Conhecimento básico de linha de comando (porque fazer coisas via downloads é estúpido …)
  • Saiba quem é Jim Carrey (porque gifs)

Se você não está familiarizado com o pug, você ainda pode gerenciar o seu caminho através disso. Mas se você tiver tempo, leia sobre isso. Eu recomendo aprender pug com pugs . Ou seus docs . Aqueles estão bem também, eu acho.

Aqui estão as versões que usei para isso:

  • html-loader: 0.5.5,
  • html-webpack-plugin: 3.2.0,
  • pug-html-loader: 1.1.5,
  • Webpack: 4.12.0
  • webpack-cli: 3.0.8
  • npm: 6.1.0
  • nó: 10.4.0

Passo 1. Organize sua estrutura de projeto

É assim que gosto de organizar minha pasta para esses tipos de projetos.

 src / 
oldHTML /
dist /
imagens /
css /
webpack.config

Eu gosto de colocar todo o HTML original em uma pasta separada que não posso excluir acidentalmente. O Webpack é um pouco mais gentil do que o Gulp, que eu deletei uma pasta inteira antes de ?. Essa estrutura é boa o suficiente para começarmos.

Etapa 2. Aprimore o mecanismo npm

Aparte: Eu recentemente npm para npm de yarn por alguns motivos. Uma delas foi que parou de funcionar e eu tive pouca paciência para fazê-lo funcionar novamente. Artigo interessante aqui , se você quiser ler mais.

De qualquer forma, inicie esse npm.

 npm init -y 

Nota: (o -y é se você não quer responder a nenhuma de suas perguntas)

Instale dependências de desenvolvimento.

Não se preocupe, eu vou explicar cada um como nós vamos.

 npm install -D webpack webpack-cli pug-html-carregador html-webpack-plugin html-loader 

Adicione alguns scripts ao pacote.json

Por padrão, o package.json tem um script, mas precisamos adicionar alguns.

 "dev": "webpack --watch --mode development", 
"prod": "webpack - produção de modo"

Estes são os dois que eu gosto de incluir. O primeiro executará o Webpack no modo de desenvolvimento (observe: o sinalizador –mode é novo no Webpack 4) e atenta para as mudanças no arquivo. A segunda é quando queremos rodar o Webpack em produção, isso normalmente reduz o material.

Deve ser algo como isto:

 "name": "pugTut", 
"versão": "1.0.0",
"descrição": "",
"main": "index.js",
"scripts": {
"teste":
"dev": "webpack --watch --mode development",
"prod": "webpack - produção de modo"
}
..... mais código

Crie alguns arquivos iniciais para testar nossa configuração do Webpack

O Webpack precisa de um ponto de entrada, então vamos criar um. Crie um app.js na pasta src / . Pode estar em branco. Não importa. Também precisa de um arquivo pug inicial para compilar. Crie um arquivo index.pug na pasta src / também.

Crie e configure o webpack.config.js no diretório raiz

Tudo bem, se você não usou o Webpack antes, eu vou percorrer cada parte individualmente para dar a você (e espero que eu) uma ideia do wtf acontecendo neste arquivo de configuração.

Primeiro, vamos declarar nossas dependências.

 // webpack.config.js 
caminho const = require ('caminho');
const webpack = require ('webpack');
const HtmlWebpackPlugin = require ('html-webpack-plugin');

path é uma dependência nativa nativa, portanto você não deve se preocupar com isso sendo necessário em seu package.json.

Webpack é, bem Webpack …

HtmlWebpackPlugin é como extraímos HTML. Não sou especialista em como o Webpack funciona. Pelo que entendi, uma vez que é projetado para consumir JavaScript, temos que ter carregadores em nosso arquivo de configuração para extrair coisas como HTML e CSS. HtmlWebpackPlugin é como fazemos algo útil com o HTML extraído dos carregadores.

Legal? Próximo passo…

 const pug = { 
teste: /.pug$/,
use: ['html-loader? attrs = false', 'pug-html-loader']
};

Este método é usado por Wes Bos e eu realmente gosto disso, então eu uso. Temos que definir regras sobre como lidar com certos tipos de arquivos, por exemplo, .pug ou .css. Colocá-lo em uma variável torna mais legível, na minha opinião. De qualquer forma, configuramos um caso de teste com um regexp e definimos os loaders que queremos usar. Por alguma razão, os carregadores são listados na ordem inversa do que você pensa. Tenho certeza de que há uma explicação, mas não consegui encontrar.

Confuso? O que isso significa é que, se quisermos usar pug para compilar em HTML, escrevemos na ordem acima: nosso carregador de html -> pug loader . No entanto, na realidade, quando o código é executado, ele executa o pug loader primeiro … depois o carregador de HTML . Sim.

Nota: Não se preocupe com ?attrs=false por agora, vou explicar isso um pouco mais tarde.

Legal? Próximo passo…

 const config = { 
entrada: './src/app.js',
output: {
caminho: path.resolve (__ dirname, 'dist'),
nome do arquivo: '[name] .bundle.js'
}
module: {
regras: [pug]
}
plugins: [
novo HtmlWebpackPlugin ({
nome do arquivo: 'index.html',
template: 'src / index.pug',
injetar: falso
})
]
};
 module.exports = config; 

Puta merda. Isso é um monte de coisas. Vamos acabar com isso.

A entrada é simplesmente o ponto de entrada para o nosso arquivo JS.

A saída define onde queremos que nosso arquivo JS seja enviado . Não é para onde nossos arquivos HTML irão. Como mencionado acima, o caminho é um módulo do nó. __dirname é uma variável que podemos obter do Node. O nome do arquivo é o que queremos chamar de nosso arquivo JS. O [name] é uma substituição. Nesse caso, ele usa o nome do arquivo de entrada. Você também pode usar [hash] se quiser um identificador exclusivo.

módulo define os diferentes módulos. Para o propósito deste tutorial, existe apenas um módulo com um conjunto de regras. regras define as regras que usaremos para esse módulo. Nós jogamos a variável pug que nós fizemos anteriormente. Tão bom, tão limpo.

Finalmente, plugins é onde nós adicionamos qualquer coisa de terceiros. No nosso caso, estamos usando o HtmlWebpackPlugin para fazer algo com nossos arquivos pug.

filename é o que queremos que nosso arquivo HTML seja chamado. template é o arquivo pug que está compilando. injeção é: "injetar todos os ativos no modelo dado." Eu tenho que definir como falso porque … bem, honestamente não me lembro.

Uma das coisas mais ruins sobre o HtmlWebpackPlugin é que você precisa criar uma entrada para TODOS os arquivos HTML. Eu tentei descobrir uma maneira de contornar isso, mas não encontrei soluções simples.

 // webpack.config.js 
caminho const = require ('caminho');
const webpack = require ('webpack');
const HtmlWebpackPlugin = require ('html-webpack-plugin');
 const pug = { 
teste: /.pug$/,
use: ['html-loader? attrs = false', 'pug-html-loader']
};
 const config = { 
entrada: './src/app.js',
output: {
caminho: path.resolve (__ dirname, 'dist'),
nome do arquivo: '[name] .bundle.js'
}
module: {
regras: [pug]
}
plugins: [
novo HtmlWebpackPlugin ({
nome do arquivo: 'index.html',
template: 'src / index.pug',
injetar: falso
})
]
};
 module.exports = config; 

Antes de prosseguirmos, vamos nos certificar de que nosso código funciona! Execute o script.

 npm run dev 

Se tudo correu bem, você deve ver algo assim:

Nós percorremos um longo caminho. Aqui está um presente:

Etapa 3. Divida as páginas em parciais

É aqui que a mágica começa a acontecer. Eu sei que parece que estamos trabalhando por um tempo com muito pouco ganho, mas confie em mim … valeu a pena.

Uma das características mais importantes para o pug são os parciais. A ideia é ter um arquivo que contenha a maior parte do seu código global (cabeçalho, cabeçalho, rodapé, navegação e assim por diante) e tenha arquivos individuais para todo o seu conteúdo.

Vamos fazer alguns arquivos. Você deveria ter criado o arquivo index.pug , mas vamos fazer mais um layout.pug .

 src / 
- index.pug
- layout.pug

Etapa 4. Arquivo de layout de instalação

O arquivo de layout é basicamente o modelo principal para todo o seu site. Ele conterá todas as coisas globais, por exemplo, cabeçalho, cabeçalho e rodapé.

 // - layout.pug 
doctype html
html
cabeça
título eu sou um título
corpo
cabeçalho de bloco
bloquear conteúdo
rodapé do bloco
script (src = "somescript.js")

Eu acho que algo para explicar é que o pug é baseado no recuo, similar ao YAML. É glorioso, porque isso significa mais tags de fechamento! No entanto, isso pode jogar alguns, especialmente aqueles com recuo de baixa qualidade para começar. Portanto, apenas certifique-se de começar devagar e certifique-se de que tudo esteja corretamente recuado e você ficará bem.

Olhando para o nosso arquivo layout.pug, você verá algumas tags HTML familiares misturadas com as desconhecidas. Eu sugiro que você baixe o realce de sintaxe para o pug no seu editor de escolha. Se você estiver usando o VSCode, ele deve vir com ele por padrão. Obrigado Microsoft.

Eu acho que é muito fácil descobrir, mas vamos dar uma olhada na carne do documento para ter certeza de que sabemos o que está acontecendo.

 cabeça 
título eu sou um título
corpo
cabeçalho de bloco
bloquear conteúdo
rodapé do bloco
script (src = "somescript.js")

cabeça , corpo , título e script são tags normais, mas o que diabos é bloco ? block é como definimos o conteúdo dinâmico. Basicamente, isso é um pug dizendo que algum conteúdo vai entrar aqui. Espero que faça mais sentido quando criarmos nossos arquivos de páginas individuais.

Etapa 5. Crie mais parciais

Vamos fazer uso desse arquivo index.pug.

 // - index.pug 
estende o layout
 bloquear conteúdo 
p Woah.

Olhando para o nosso arquivo de índice, parece muito pequeno para uma página HTML inteira. É por causa disso que pouco se extende . extends diz ao pug que você quer usar outro arquivo pug como modelo, no layout do nosso caso . Então, abaixo desse bloco, está em referência ao que colocamos em nosso arquivo layout.pug .

Se o seu Webpack ainda estiver rodando em segundo plano, ele deverá recompilar e você obterá um novo index.html na sua pasta dist / . Caso contrário, execute o Webpack novamente.

Etapa 6. Pegue todo o HTML antigo

Esses arquivos iniciais são bons e elegantes, mas precisamos fazer algum progresso real. Precisamos começar a pegar esse HTML e usá-lo! Felizmente, o pug reconhecerá tags HTML antigas regulares, para que você possa literalmente copiar todo o conteúdo HTML que desejar e apenas colá-lo lá.

Pode parecer algo assim:

 estende o layout 
 bloquear conteúdo 
<h1> blerb </ h1>
<p> Woah. </ p>

Tudo bem, não é tão simples assim.

Como eu mencionei, o pug é baseado no recuo. Para tornar a vida mais fácil, sugiro remover todo o recuo do arquivo HTML antes de colar no arquivo pug. Isso funcionará principalmente, mas você provavelmente terá que improvisar um pouco. Para nossa sorte, o pug-html-loader nos diz o que há de errado com ele quando tenta compilar. Existem alguns exemplos de problemas comuns na próxima etapa.

Etapa 7. Comece a otimizar

Eu não vou mentir, quando você joga pela primeira vez em HTML, o Webpack não vai gostar. Aqui estão algumas coisas para procurar:

Imagens

  1. Certifique-se de que os links para as imagens sejam bons. Por alguma razão, muitas vezes falha se o src = “images /” em vez de src = “/ images /”

2. Prometi anteriormente voltar ao que ?attrs=false foi, bem, aqui estamos nós!

Esta é a sinopse do site do html-loader explicando o que isso faz.

Para desabilitar completamente o processamento de atributos de tags (por exemplo, se você está lidando com o carregamento de imagens no lado do cliente), você pode passar attrs=false .

 html-loader? attrs = false 

Javascript

pug não joga legal com JS em tags de script. Se você estiver colando na abertura e fechamento regular das tags do script JS, isso pode funcionar bem. No entanto, se você quiser usar a tag de script pug, apenas adicione um ponto no final, como este:

 src. 
função imAFunction () {console.log ('Eu corri!')}

Passo 8. Crie mais páginas e comece a converter para tags pug

Claramente, é inútil se você está apenas fazendo a página de índice. Para o que você está fazendo, basta criar um novo arquivo para cada página desejada. Além disso, certifique-se de criar novas entradas do HtmlWebpackPlugin na seção de plugins do Webpack.

Vai acabar ficando assim:

 //webpack.config.js 
 ... código anterior ... 
plugins: [
novo HtmlWebpackPlugin ({
nome do arquivo: 'index.html',
template: 'src / index.pug',
injetar: falso
}),
novo HtmlWebpackPlugin ({
nome do arquivo: 'contact.html',
template: 'src / contact.pug',
injetar: falso
})
]
... mais código ...

Você não precisa converter tudo para o formato pug imediatamente. Na verdade, se você tem um site enorme com uma porcaria de HTML, então pode fazê-lo à medida que avança, mas fica mais fácil.

Inclui

Isso não seria um tutorial muito bom se não falássemos sobre inclusões. Lembre-se daqueles blocos no arquivo de layout? Bem, se você não quer que o arquivo de layout seja gigante, você pode criar arquivos separados que serão puxados em tempo de compilação. Por exemplo, se você quiser criar um único arquivo que contenha todas as informações do cabeçalho. Quebrar isso dessa maneira também ajuda substancialmente com o recuo.

Crie um novo arquivo “cabeçalho” em uma nova pasta “includes”:

 src / 
- inclui /
header.pug

Nesse arquivo, coloque o que você quer estar no cabeçalho.

 // - header.pug 
cabeçalho
h1 eu sou um cabeçalho

Agora volte para layout.pug e inclua-o.

 // - layout.pug 
doctype html
html
cabeça
título eu sou um título
corpo
cabeçalho de bloco
incluir inclui / cabeçalho
bloquear conteúdo
rodapé do bloco
script (src = "somescript.js")

Etapa 7. Quer ficar chique?

Há muito mais coisas que você pode fazer com o pug e o webpack. No entanto, acho que chegamos ao fim do básico. Ainda assim, confira mixins . Essas coisas são incríveis.

Empacotando

Eu sugiro trazer o HTML lentamente, caso contrário, você acabará depurando 1.000 erros de uma só vez.

Isso encerra a nossa pequena conversa de mão única. Espero que tenham gostado do conhecimento e da quantidade obscena de Jim Carrey. Aqui está mais um, para uma boa medida. No caso de você estar acompanhando, há 7 Jim Gifs.

Referências

Aqui está um ótimo artigo sobre o Webpack 4. Altamente recomendável.

Um conto de Webpack 4 e como finalmente configurá-lo da maneira certa
Spoiler: não há jeito certo. #justwebpackthings hackernoon.com

https://pugjs.org/