uma batalha épica de temas de gerador de sites estáticos

[ad_1]

Uma comparação das nuances da criação de temas para os dois principais geradores de sites estáticos.

Recentemente, assumi a tarefa de criar um tema de site de documentação para dois projetos. Ambos os projetos precisavam dos mesmos recursos básicos, mas um usa Jekyll enquanto o outro usa Hugo.

Na racionalidade típica do desenvolvedor, havia claramente apenas uma opção. Decidi criar o mesmo tema nos dois quadros e dar a você, caro leitor, uma comparação lado a lado.

Esta postagem não é um guia abrangente de criação de temas, mas pretende familiarizar você com o processo de criação de um tema em qualquer um dos geradores. Aqui está o que abordaremos:

Como os arquivos de tema são organizados
Onde colocar conteúdo
Como funciona o modelo
Criando um menu de nível superior com o pages objeto
Criando um menu com links aninhados a partir de uma lista de dados
Montando o modelo
Criando estilos
Como configurar e implantar nas páginas do GitHub

Aqui está um wireframe de baixa qualidade do tema que vou criar.

Se você planeja construir junto, pode ser útil veicular o tema localmente enquanto você o constrói; os dois geradores oferecem essa funcionalidade. Para Jekyll, corra jekyll servee para Hugo, hugo serve.

Existem dois elementos principais: a área de conteúdo principal e o importante menu da barra lateral. Para criá-los, você precisará de arquivos de modelo que digam ao gerador de sites como gerar a página HTML. Para organizar os arquivos de modelo de tema de maneira sensata, primeiro você precisa saber qual estrutura de diretório o gerador de sites espera.

Como os arquivos de tema são organizados

O Jekyll suporta temas baseados em gemas, que os usuários podem instalar como qualquer outra gema Ruby. Esse método oculta arquivos de tema na gema. Portanto, para os fins dessa comparação, não estamos usando temas baseados em gemas.

Quando você corre jekyll new-theme , Jekyll criará um novo tema para você. Veja como são esses arquivos:

.├── assets├── Gemfile├── _includes├── _layouts│   ├── default.html│   ├── page.html│   └── post.html├── LICENSE.txt├── README.md├── _sass└── .gemspec

Os nomes dos diretórios são adequadamente descritivos. o _includes O diretório é para pequenos pedaços de código que você reutiliza em lugares diferentes, da mesma maneira que você coloca manteiga em tudo. (Só eu?) _layouts O diretório contém modelos para diferentes tipos de páginas no seu site. o _sass pasta é para Sass arquivos usados para criar a folha de estilo do seu site.

Você pode criar um novo tema de Hugo executando hugo new theme . Possui estes arquivos:

.├── archetypes│   └── default.md├── layouts│   ├── 404.html│   ├── _default│   │   ├── baseof.html│   │   ├── list.html│   │   └── single.html│   ├── index.html│   └── partials│       ├── footer.html│       ├── header.html│       └── head.html├── LICENSE├── static│   ├── css│   └── js└── theme.toml

Você pode ver algumas semelhanças. Os arquivos de modelo de página de Hugo estão dobrados layouts/. Observe que o _default O tipo de página possui arquivos para um list.html e um single.html. Ao contrário de Jekyll, Hugo usa esses nomes de arquivos específicos para distinguir entre listar páginas (como uma página com links para todas as suas postagens) e páginas únicas (como uma das postagens do seu blog). o layouts/partials/ O diretório contém os bits reutilizáveis amanteigados, e os arquivos da folha de estilo têm um local escolhido em static/css/.

Essas estruturas de diretório não são definidas, pois os dois geradores de sites permitem alguma medida de personalização. Por exemplo, Jekyll permite definir coleções, e Hugo faz uso de pacotes de páginas. Esses recursos permitem que você organize seu conteúdo de várias maneiras, mas, por enquanto, vamos ver onde colocar algumas páginas simples.

Onde colocar conteúdo

Para criar um menu de site parecido com este:

Introduction    Getting Started    Configuration    DeployingAdvanced Usage    All Configuration Settings    Customizing    Help and Support

Você precisará de duas seções (“Introdução” e “Uso avançado”) contendo as respectivas subseções.

Jekyll não é rigoroso com a localização do conteúdo. Ele espera páginas na raiz do seu site e criará o que estiver lá. Veja como você pode organizar essas páginas na raiz do site Jekyll:

.├── 404.html├── assets├── Gemfile├── _includes├── index.markdown├── intro│   ├── config.md│   ├── deploy.md│   ├── index.md│   └── quickstart.md├── _layouts│   ├── default.html│   ├── page.html│   └── post.html├── LICENSE.txt├── README.md├── _sass├── .gemspec└── usage    ├── customizing.md    ├── index.md    ├── settings.md    └── support.md

Você pode alterar a localização da fonte do site no seu Configuração do Jekyll.

Em Hugo, todo o conteúdo renderizado é esperado no content/ pasta. Isso impede que Hugo tente renderizar páginas que você não deseja, como 404.html, como conteúdo do site. Veja como você pode organizar sua content/ Diretório em Hugo:

.├── _index.md├── intro│   ├── config.md│   ├── deploy.md│   ├── _index.md│   └── quickstart.md└── usage    ├── customizing.md    ├── _index.md    ├── settings.md    └── support.md

Para Hugo, _index.md e index.md significa coisas diferentes. Pode ser útil saber que tipo de Pacote de Páginas você deseja para cada seção: Folha, que não tem filhos, ou Filial.

Agora que você tem uma idéia de onde colocar as coisas, vejamos como criar um modelo de página.

Como funciona o modelo

Os modelos de página Jekyll são criados com o Linguagem de modelagem líquida. Ele usa chaves para gerar conteúdo variável para uma página, como o título da página: {{ page.title }}.

Os modelos de Hugo também usam chaves, mas são construídos com Ir modelos. A sintaxe é semelhante, mas diferente: {{ .Title }}.

Os modelos Liquid e Go podem lidar com lógica. Usos líquidos Tag sintaxe para denotar operações lógicas:

{% if user %}  Hello {{ user.name }}!{% endif %}

O And Go Templates coloca suas funções e argumentos em sua sintaxe de chaves:

{{ if .User }}    Hello {{ .User }}!{{ end }}

As linguagens de modelagem permitem criar uma página HTML esquelética e depois instruir o gerador de sites a colocar conteúdo variável nas áreas definidas. Vamos comparar dois possíveis default modelos de página para Jekyll e Hugo.

Andaime de Jekyll default tema é simples, então veremos o tema inicial Mínimos. Aqui está _layouts/default.html em Jekyll (líquido):

  {%- include head.html -%}      {%- include header.html -%}                  {{ content }}      
    
    {%- include footer.html -%}

Aqui está o tema do andaime de Hugo layouts/_default/baseof.html (Ir modelos):

    {{- partial "head.html" . -}}            {{- partial "header.html" . -}}                {{- block "main" . }}{{- end }}        
        {{- partial "footer.html" . -}}

Sintaxe diferente, mesma ideia. Ambos os modelos extraem bits reutilizáveis para head.html, header.htmle footer.html. Elas aparecem em muitas páginas, por isso faz sentido não ter que se repetir. Ambos os modelos também possuem um local para o conteúdo principal, embora o modelo Jekyll use uma variável ({{ content }}) enquanto Hugo usa um bloco ({{- block "main" . }}{{- end }}) Blocos são apenas outra maneira de Hugo permitir que você defina bits reutilizáveis.

Agora que você sabe como a modelagem funciona, você pode criar o menu da barra lateral para o tema.

Você pode criar programaticamente um menu de nível superior a partir de suas páginas. Isso parecerá assim:

IntroductionAdvanced Usage

Vamos começar com Jekyll. Você pode exibir links para as páginas do site em seu modelo Liquid, percorrendo o site.pages objeto que Jekyll fornece e construindo uma lista:

    {% for page in site.pages %}    {{ page.title }}
    {% endfor %}

Isso retorna todas as páginas do site, incluindo todas as que você talvez não queira, como 404.html. Você pode filtrar as páginas que realmente deseja com mais algumas tags, como incluir condicionalmente as páginas se elas tiverem um section: true conjunto de parâmetros:

    {% for page in site.pages %}    {%- if page.section -%}    {{ page.title }}
    {%- endif -%}    {% endfor %}

Você pode obter o mesmo efeito com um pouco menos de código no Hugo. Passar por Hugo .Pages objeto usando o Go Template range açao:

{{ range .Pages }}            {{.Title}}    
{{ end }}

Este modelo usa o .Pages objeto para retornar todas as páginas de nível superior em content/ do seu site Hugo. Como Hugo usa uma pasta específica para o conteúdo do site que você deseja renderizar, não há filtragem adicional necessária para criar um menu simples de páginas do site.

Os dois geradores de sites podem usar uma lista de links definida separadamente para renderizar um menu no seu modelo. Isso é mais adequado para criar links aninhados, como este:

Introduction    Getting Started    Configuration    DeployingAdvanced Usage    All Configuration Settings    Customizing    Help and Support

Jekyll suporta arquivos de dados em alguns formatos, incluindo YAML. Aqui está a definição para o menu acima em _data/menu.yml:

section:  - page: Introduction    url: /intro    subsection:      - page: Getting Started        url: /intro/quickstart      - page: Configuration        url: /intro/config      - page: Deploying        url: /intro/deploy  - page: Advanced Usage    url: /usage    subsection:      - page: Customizing        url: /usage/customizing      - page: All Configuration Settings        url: /usage/settings      - page: Help and Support        url: /usage/support

Veja como renderizar os dados no modelo da barra lateral:

{% for a in site.data.menu.section %}{{ a.page }}    {% for b in a.subsection %}    {{ b.page }}
    {% endfor %}
{% endfor %}

Esse método permite criar um menu personalizado, com dois níveis de aninhamento. Os níveis de aninhamento são limitados pelo for loops no modelo. Para uma versão recursiva que lida com níveis adicionais de aninhamento, consulte Navegação em árvore aninhada com recursão.

Hugo faz algo semelhante com a sua modelos de menu. Você pode definir links de menu em seu Hugo site confige até mesmo adicionar propriedades úteis que Hugo entende, como ponderação. Aqui está uma definição do menu acima em config.yaml:

sectionPagesMenu: mainmenu:    main:    - identifier: intro      name: Introduction      url: /intro/      weight: 1    - name: Getting Started      parent: intro      url: /intro/quickstart/      weight: 1    - name: Configuration      parent: intro      url: /intro/config/      weight: 2    - name: Deploying      parent: intro      url: /intro/deploy/      weight: 3    - identifier: usage      name: Advanced Usage      url: /usage/    - name: Customizing      parent: usage      url: /usage/customizing/      weight: 2    - name: All Configuration Settings      parent: usage      url: /usage/settings/      weight: 1    - name: Help and Support      parent: usage      url: /usage/support/      weight: 3

Hugo usa o identifier, que deve corresponder ao nome da seção, junto com o parent variável para lidar com o aninhamento. Veja como renderizar o menu no modelo da barra lateral:

    {{ range .Site.Menus.main }}    {{ if .HasChildren }}            {{ .Name }}    
            {{ range .Children }}                    {{ .Name }}        
        {{ end }}    
    {{ else }}            {{ .Name }}    
    {{ end }}    {{ end }}

o range A função itera sobre os dados do menu e a de Hugo .Children A variável manipula páginas aninhadas para você.

Montando o modelo

Com o seu menu na sua barra lateral reutilizável (_includes/sidebar.html para Jekyll e partials/sidebar.html para Hugo), você pode adicioná-lo ao default.html modelo.

Em Jekyll:

{%- include head.html -%}    {%- include sidebar.html -%}    {%- include header.html -%}            {{ content }}    
    {%- include footer.html -%}

Em Hugo:

{{- partial "head.html" . -}}    {{- partial "sidebar.html" . -}}    {{- partial "header.html" . -}}            {{- block "main" . }}{{- end }}    
    {{- partial "footer.html" . -}}

Quando o site é gerado, cada página conterá todo o código do seu sidebar.html.

Criar uma folha de estilo

Os dois geradores de sites aceitam o Sass para criar folhas de estilo CSS. Jekyll possui processamento Sass integradoe Hugo usa Hugo Pipes. Ambas as opções têm algumas peculiaridades.

Sass e CSS em Jekyll

Para processar um arquivo Sass no Jekyll, crie suas definições de estilo no diretório _sass diretório. Por exemplo, em um arquivo em _sass/style-definitions.scss:

$background-color: #eef !default;$text-color: #111 !default;body {  background-color: $background-color;  color: $text-color;}

Jekyll não gerará esse arquivo diretamente, pois processa apenas arquivos com matéria de frente. Para criar o caminho do arquivo de resultado final para a folha de estilo do seu site, use um espaço reservado com a frente vazia onde você deseja .css arquivo para aparecer. Por exemplo, assets/css/style.scss. Neste arquivo, basta importar seus estilos:

------@import "style-definitions";

Essa configuração bastante hackeada tem uma vantagem: você pode usar tags e variáveis de modelo Liquid no seu arquivo de espaço reservado. Essa é uma ótima maneira de permitir que os usuários definam variáveis do site _config.yml, por exemplo.

A folha de estilo CSS resultante no site gerado possui o caminho /assets/css/style.css. Você pode vincular a ele no site head.html usando:

Sass e Hugo Pipes em Hugo

Hugo usa Hugo Pipes processar Sass para CSS. Você pode conseguir isso usando a função de processamento de ativos de Hugo, resources.ToCSS, que espera uma fonte no assets/ diretório. Leva o arquivo SCSS como argumento. Com suas definições de estilo em um arquivo Sass em assets/sass/style.scss, veja como obter, processar e vincular seu Sass no tema head.html:

{{ $style := resources.Get "/sass/style.scss" | resources.ToCSS }}

Hugo processamento de ativos requer Hugo estendido, que você pode não ter por padrão. Você pode estender Hugo do página de lançamentos.

Configurar e implantar nas páginas do GitHub

Antes de o gerador do site poder criar seu site, ele precisa de um arquivo de configuração para definir alguns parâmetros necessários. Os arquivos de configuração estão no diretório raiz do site. Entre outras configurações, você pode declarar o nome do tema a ser usado ao criar o site.

Configurar o Jekyll

Aqui está um mínimo _config.yml para Jekyll:

title: Your awesome titledescription: >- # this means to ignore newlines until "baseurl:"  Write an awesome description for your new site here. You can edit this  line in _config.yml. It will appear in your document head meta (for  Google search results) and in your feed.xml site description.baseurl: "" # the subpath of your site, e.g. /blogurl: "" # the base hostname & protocol for your site, e.g. http://example.comtheme: # for gem-based themesremote_theme: # for themes hosted on GitHub, when used with GitHub Pages

Com remote_theme, qualquer O tema Jekyll hospedado no GitHub pode ser usado com sites hospedados nas páginas do GitHub.

Jekyll tem um configuração padrão, portanto, todos os parâmetros adicionados ao seu arquivo de configuração substituirão os padrões. Aqui estão definições de configuração adicionais.

Configure Hugo

Aqui está um exemplo mínimo de Hugo config.yml:

baseURL: https://example.com/ # The full domain your site will live atlanguageCode: en-ustitle: Hugo Docs Sitetheme: # theme name

Hugo não faz suposições. Portanto, se um parâmetro necessário estiver ausente, você verá um aviso ao criar ou veicular seu site. Aqui estão todas as definições de configuração para Hugo.

Implantar nas páginas do GitHub

Ambos os geradores constroem seu site com um comando.

Para Jekyll, use jekyll build. Vejo mais opções de compilação aqui.

Para Hugo, use hugo. Você pode correr hugo help ou veja mais opções de compilação aqui.

Você terá que escolher a fonte do seu site GitHub Pages; Depois de concluído, seu site será atualizado sempre que você enviar uma nova compilação. Obviamente, você também pode automatizar sua compilação de páginas do GitHub usando as ações do GitHub. Aqui está um para construindo e implantando com Hugoe um para construindo e implantando Jekyll.

Altura de começar!

Todas as diferenças substanciais entre esses dois geradores estão ocultas; mesmo assim, vamos dar uma olhada nos temas finalizados, em duas variações de cores.

Aqui está o Hugo:

Aqui está o Jekyll:

Espera quem ganhou?

🤷

Hugo e Jekyll têm suas peculiaridades e conveniências.

Da perspectiva deste desenvolvedor, Jekyll é uma opção viável para sites simples sem necessidades organizacionais complicadas. Se você deseja renderizar algumas postagens de uma página em um tema disponível e, hospedando as páginas do GitHub, o Jekyll o colocará em funcionamento rapidamente.

Pessoalmente, eu uso Hugo. Gosto das capacidades organizacionais de seus pacotes de páginas e é apoiado por uma equipe dedicada e consciente que realmente parece se esforçar para facilitar a conveniência de seus usuários. Isso é evidente nas muitas funções de Hugo e em truques úteis como Processamento de imagem e Códigos de acesso. Eles parecem lançar novas correções e versões com a mesma frequência que eu preparo uma xícara de café – o que, dependendo do seu caso de uso, pode ser fantástico ou irritante.

Se você ainda não consegue decidir, não se preocupe. o Tema da documentação do OpenGitDocs Eu criei está disponível para Hugo e Jekyll. Comece com um, alterne mais tarde, se desejar. Esse é o benefício de ter opções.

[ad_2]

Fonte