Ir para o conteúdo

Guia de estilo de nossas páginas⚓︎

Neste post definiremos algumas regras simples, mas muito efetivas, para manter o padrão entre as páginas deste ou qualquer outro site sob nossa responsabilidade. Criados com auxílio da ferramenta MkDocs e um de seus temas mais famosos, Material2, estes conteúdos estão, quase que exclusivamente, em arquivos de texto no formato Markdown (.md).

Neste sentido, proponho as seguintes regras durante a elaboração de conteúdo nos arquivos .md:

Blog post⚓︎

  • Escritos em arquivos .md dentro de uma pasta principal docs/blog/posts:
- docs
  - blog
    - posts
      - yyyymmaa_nome_post_reduzido.md
  • Nome da arquivo do post deverá sempre iniciar com data no padrão yyyymmaa3.
  • Imagens deverão ser incluídas em formato .webp na conta Cloudinary da diretoria.
  • Vídeos deveráo ser incluídos no canal YouTube da diretoria.
  • Posts não finalizados deverão ser marcados com a propriedade draft: true:

If you mark a post as a draft, a red marker appears next to the post date on index pages. When the site is built, drafts are not included in the output. This behavior can be changed, e.g. for rendering drafts when building deploy previews.

Cabeçalhos⚓︎

  • Somente primeira letra maiúscula1.
  • Título da página definido com heading level 1 (#).
  • Demais cabeçalhos da página definidos com heading level 2 (##).
  • Não utilizar heading level 3 em diante.

Listas⚓︎

  • Somente primeira letra maiúscula1.
  • Finalizados com pontos (.) e não com ponto e vírgula (;).
  • Inclusão de itens na navbar ocorrerá sempre pela propriedade nav do arquivo mkdocs.yml:
  • Isso visa garantir a inclusão de acentos e caracteres especiais nos títulos das páginas.
# Arquivo mkdocs.yml na raiz do repositório

nav:
  - index.md
  - Cursos:
    - cursos/index.md
    - Pythomatiza:
      - cursos/python_w3schools/index.md
      - Aula 001: cursos/python_w3schools/001.md
      - Aula 002: cursos/python_w3schools/002.md
      - Aula 003: cursos/python_w3schools/003.md
      - Aula 004: cursos/python_w3schools/004.md
      - Aula 005: cursos/python_w3schools/005.md
      - Aula 006: cursos/python_w3schools/006.md
      - Aula 007: cursos/python_w3schools/007.md
      - Aula 008: cursos/python_w3schools/008.md
      - Aula 009: cursos/python_w3schools/009.md
  - Blog:
    - blog/index.md
  - Linha do Tempo:
    - linha_do_tempo/index.md
    - Projeto FHEMIG: linha_do_tempo/projeto_fhemig.md
    - Projeto SEPLAG - CET: linha_do_tempo/projeto_seplag_cet.md
    - Projeto SEJUSP: linha_do_tempo/projeto_sejusp_sulot.md
    - Projeto SEPLAG - SCAP: linha_do_tempo/projeto_seplag_scap.md
    - Projeto SCPMSO: linha_do_tempo/projeto_seplag_scpmso.md
    - Projeto SEE: linha_do_tempo/projeto_see_fgts.md

Nomenclatura de arquivos e pastas⚓︎

  • Arquivos e pastas serão sempre nomeados no padrão snake small case.
  • Arquivos e pastas deverão ser criados, preferencialmente, dentro da pasta docs.

Parágrafos⚓︎

  • Somente primeira letra maiúscula1.
  • Para simplificar o processo de revisão dos arquivos .md, incluir cada frase em uma linha.
  • A separação entre parágrafos deverá ser feita com a utilização de uma linha em branco entre um bloco de frases ou parágrafos.

Robôs⚓︎

  • Especificamente para páginas de robôs do site Automatiza.MG.
  • Criado em arquivo index.md dentro de uma pasta principal que deverá ser criada com a seguinte estrutura:
- docs
  - robos
    - nome_robo
      - assets
        - fluxo.md
        - arquivo_auxiliar_1.csv
        - arquivo_auxiliar_2.pdf
      - index.md
  • Pasta assets deverá conter com, no mínimo fluxo.md do robô.
  • Imagens deverão ser incluídas em formato .webp na conta Cloudinary da diretoria.
  • Vídeos deveráo ser incluídos no canal YouTube da diretoria.

Tags⚓︎

  • Tags são categorias padronizadas para facilitar a busca de conteúdo em cada site.
  • Deverão ser evitadas tags com duas palavras. Tente utilizar apenas uma palavra, sempre que possível, englobando todas as características principais de um grupo de robôs4.

  1. Com exceção de nomes próprios e ou siglas. ↩↩↩

  2. Use e abuse da documentação do tema Material para criar páginas cada vez mais atrativas. ↩

  3. Ano com quatro dígitos, mês e dia com do dois. Exemplo 20231025. ↩

  4. O Issue número 5 do repositório automatizações contém discussão inicial para a criação de guia de estilo para tags. ↩

Comentários