Skip to content

Efetuar Alterações

Estrutura do Site

Antes de se começar a efetuar alterações ao conteúdo, é importante perceber como está estruturado o site.

$ tree
.
├── content
│   ├── ...
│   ├── fis-i
│   │   ├── 0001-kinematics-1d.md
│   │   ├── 0002-kinematics-2d.md
│   │   ├── assets
│   │   │   ├── 0001-path.png
│   │   │   ├── ...
│   │   │   └── 0002-projectile-launch-velocity-vector-decomposition.svg
│   │   ├── cheatsheets
│   │   │   └── 0001-main-cheatsheet.md
│   │   ├── exercicios
│   │   │   └── 0999-fichas-2021-2022.md
│   │   ├── guides
│   │   │   ├── 0001-recap-highschool.md
│   │   │   └── assets
│   │   │       ├── 0001-force-decomposition.svg
│   │   │       ├── 0001-inclined-plane.svg
│   │   │       └── 0001-movement-graphs.svg
│   │   └── index.md
│   └── ...
├── plugins
│   └── ...
├── src
│   └── ...
├── README.md
└── ...

A pasta content tem todo o conteúdo do site e é onde nos vamos focar, visto que tudo o resto é relacionado com o site em si.
Dento da pasta content existem várias pastas, uma para cada UC do curso. De forma a facilitar a gestão de conteúdos, cada UC tem um maintainer associado, que será quem irá aceitar/rejeitar as alterações propostas.

Dentro da pasta de cada UC, encontram-se ficheiros do tipo XXXX-nome-da-pagina.md, uma pasta assets, um ficheiro index.md e possivelmente outras pastas.

  • index.md: Página principal da UC, onde normalmente se encontra uma pequena descrição sobre a mesma, assim como alguns recursos úteis ou outras informações importantes.
  • XXXX-nome-da-pagina.md: Uma página com conteúdo. XXXX refere-se ao identificador incremental da página de forma a manter a ordem na sidebar.
  • assets: Pasta onde se guarda ficheiros auxiliares, como imagens. Geralmente, usa-se o formato XXXX-pequena-descricao.png onde XXXX é o identificador da página onde são usados.

Criar um Novo Branch

Antes de começares a efetuar alterações, deves criar um branch. Isto também se pode fazer no final, mas depois corre-se o risco de nos esquecermos.
Quando fores submeter alterações, vais fazê-lo ao submeter o teu branch. Podes pensar num branch como um conjunto de alterações face ao atual.

O que é um branch?

No contexto de desenvolvimento de software, um branch deve ser criado quando se pretende adicionar uma nova feature, corrigir um bug existente, etc. Aqui temos algo semelhante, mas para alterações.

É boa prática agrupar alterações relacionadas num só branch, sendo que um branch pode ter vários commits.

Por exemplo, se quisermos fazer resumos de CDI-I e BD e corrigir erros ortográficos de uma página de SO, devemos criar os seguintes branches, através do comando git branch <branch name>.

  • git branch cdi1/add-content-sucessoes;
  • git branch bd/add-content-dmbs;
  • git branch so/fix-typos.

Para mudar de branch, deves fazer git checkout <branch name>, sendo que o nome do default branch é master.

Note

Os nomes dos branches são arbitrários, pelo que podes lhes dar o nome que quiseres. Os nomes acima servem apenas de exemplo.

Alterações para o master

Nunca faças alterações diretamente para o master! Dado que estás a trabalhar com uma fork, o teu branch master deverá estar sempre sincronizado com o branch master do repositório principal (frequentemente apelidado de upstream).

Editar Páginas Existentes

Para editar um página já existente, basta abrir o respetivo ficheiro e editar o seu conteúdo.

Os ficheiros são escritos em Markdown, pelo que é muito simples usar formatação adicional, como bold, itálico, headers, links, imagens, etc.

Os Resumos LEIC usam algumas extensões de Markdown para certo tipo de formatação, como a inserção de fórmulas matemáticas (KaTeX), cores no texto, containers (info, tip, warning, error e details), etc.

É recomendado ver a Referência Markdown para uma lista completa.

Criar uma Nova Página

Como já foi referido, as páginas devem ter um nome do tipo XXXX-nome-da-pagina.md. O nome do ficheiro não deve conter acentos.

Todas as páginas começam com frontmatter, isto é, metadata que define o título, descrição, link, etc. da página.

---
title: Cinemática 1D
description: >-
  Cinemática a 1 dimensão.
  Deslocamento.
  Velocidade Média e Velocidade Instantânea.
  Aceleração Média e Aceleração Instantânea.
path: /fis-i/kinematics-1d
type: content
---
  • title: Título da página que irá aparecer na tab do browser assim como na sidebar do site. O título que aparece na página em si é independente e tem de ser definido em Markdown com um heading de nível 1.
  • description: Descrição da página. Aparece apenas quando o link é partilhado em redes sociais e/ou plataformas como Discord. Deve conter títulos de tudo o que é abordado na página.
  • path: Link da página. Deverá ser /uc/nome-da-pagina. Não deve conter acentos.
  • type: Tipo da página, que afeta o seu posicionamento na sidebar.

Os seguinte tipos de páginas estão disponíveis:

  • topLevelPage: Página principal de cada UC
  • content (default)
  • exercises
  • cheatsheets
  • guides
  • tools
  • labsProg: Laboratórios de Programação
  • misc

Finalizar Alterações

Após efetuares as tuas alterações, deves correr o formatter para garantir que o estilo de código está de acordo com as normas do projeto.

yarn format

Se tiveres um editor como o VSCode, podes instalar a extensão do Prettier para executares a formatação sempre que guardas um ficheiro.