Estrutura de arquivos e pastas Wiki no Git

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

Este artigo descreve os arquivos e a estrutura de pastas para wikis provisionados e wikis publicados como código. Para ambos os tipos de wiki, os arquivos são armazenados em um repositório Git. Os arquivos podem incluir páginas de Markdown, código, imagens, anexos ou outros artefatos. Para estabelecer a sequência de apresentação dos arquivos, o Git adiciona um arquivo especial (.order) em cada pasta de repositório.

Quando você cria um projeto, um wiki não é criado por padrão. Você pode provisionar um wiki, criar um README ou publicar o código do projeto como um wiki.

Você cria seu wiki usando a interface do usuário do Azure DevOps. Em seguida, você pode editar o wiki a partir do caminho URL do repositório Git.

Arquivos de repositório e estrutura de pastas

O repositório Git para um wiki tem duas convenções de nomenclatura:

• O nome do repositório wiki é <ProjectName>.wiki onde <ProjectName> é o nome do seu projeto.
• O nome da ramificação raiz para o repositório wiki é wikiMain.

Você gerencia um repositório wiki da mesma forma que gerencia outros repositórios Git, definindo políticas de ramos no ramo wikiMain. Você também pode fazer alterações em sua filial local wikiMain e enviá-las diretamente para a filial remota sem definir nenhuma política.

Um repositório wiki consiste nos seguintes arquivos e pastas:

• Um arquivo para cada página Markdown localizada no nível raiz
• Um arquivo chamado .order localizado no nível raiz e também dentro de cada subpasta
• Uma subpasta para cada página wiki que tenha subpáginas
• Uma pasta chamada .attachments para armazenar todos os anexos usados no wiki

Convenções de nomenclatura de arquivos

O nome do ficheiro para cada página wiki corresponde ao título da página wiki. No nome do arquivo, um hífen (-) representa um espaço no título da página. Por exemplo, o título da página "Como contribuir" corresponde ao nome do ficheiro How-to-contribute.md. O caminho do URL para a página wiki inclui o nome do arquivo. Por exemplo, https://github.com/ExampleWiki/How-To/How-to-contribute.md. Essa abordagem ajuda a garantir que os links de favoritos para a página permaneçam intactos à medida que o wiki muda ao longo do tempo.

Cada página wiki corresponde a um arquivo no repositório wiki Git. As seguintes restrições aplicam-se aos nomes de ficheiros de paginação e ao tamanho do ficheiro:

• Nome do arquivo: Ao escolher um nome para o arquivo de paginação, lembre-se de que o caminho totalmente qualificado para o arquivo deve ter 235 caracteres ou menos. O caminho completo para a página consiste no URL do repositório, no caminho da pasta para o arquivo de paginação e no nome do arquivo de página. Por exemplo, https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md.

• Exclusividade: O nome do arquivo de paginação deve ser exclusivo dentro de seu local de pasta na hierarquia de repositório wiki. O nome é sensível a maiúsculas e minúsculas.

• Caracteres especiais: O nome do arquivo de paginação tem restrições sobre os seguintes caracteres especiais:

  • Sem caracteres de controle Unicode ou caracteres substitutos
  • Sem caracteres imprimíveis: barra /, barra invertida \, cardinal #
  • Nenhum símbolo de ponto . no início ou no final do nome

• Tamanho do ficheiro: O tamanho máximo do ficheiro de paginação é de 18 MB.

• Tamanho do ficheiro anexo: O tamanho máximo de qualquer anexo a um ficheiro de paginação é de 19 MB.

Caracteres especiais permitidos

Vários carateres especiais são permitidos num nome de ficheiro de página, como os dois pontos : e o hífen -. Por exemplo, você pode nomear um arquivo Markdown como FAQ:0525 ou Setup-Guide.

A tabela a seguir lista os caracteres especiais permitidos em nomes de arquivo de página wiki e a cadeia de caracteres codificada por URI correspondente:

Por exemplo, o nome do arquivo FAQ:0525 é codificado como FAQ%3A0525.

Sequência de páginas e o ficheiro .order

O arquivo .order define a sequência de páginas wiki. O Git procura esse arquivo em cada pasta para identificar a sequência para apresentar arquivos nesse local. A sequência de páginas padrão é a ordem alfabética (A a Z) por nome de arquivo.

|- parent-folder
|-- sub-folder1
|   |-- file1.md
|   |-- file2.md
|-- sub-folder2
|   |-- file3.md
|   |-- file4.md
|-- .order

Definir sequência de página personalizada

Quando uma pasta não tem um arquivo .order , o Git usa a sequência alfabética padrão.

Você pode definir uma sequência personalizada para qualquer pasta atualizando o arquivo .order na pasta, inclusive no nível raiz.

O visual a seguir mostra um exemplo de um índice wiki (TOC) e o ficheiro .order correspondente que cria o índice.

O arquivo .order altera a sequência alfabética para "Marketing" seguida de "Fabrikam Fiber".

Para obter mais informações sobre como reordenar páginas wiki, consulte Adicionar, editar e reordenar páginas wiki.

Restaurar sequência alfabética

Se uma pasta tiver uma sequência personalizada, você poderá reverter o método de classificação para alfabético seguindo estas etapas:

1. Copie o URL do clone para o wiki e abra-o em um navegador. O repositório Git para o wiki é aberto.

2. Vá para o arquivo .order que você deseja reverter e exclua o arquivo. Depois que o arquivo é excluído, o Git cria automaticamente um novo arquivo .order para esse local. O novo arquivo usa a sequência padrão.

Conteúdo relacionado

• Configurar wiki vs. publicar código como wiki
• Criar um wiki para o seu projeto de equipa
• Publicar um repositório Git em um wiki