Orbit
Ver o Seu README do Projeto em Orbit
The Docs tab renders your repository's README inside KPanel, so the project's own documentation is one click from its deployments instead of in a browser tab someone has to go and find.
A aba Docs renderiza o README do seu repositório dentro do KPanel, para que a documentação própria do projeto fique a um clique das suas implementações em vez de estar num separador do navegador que alguém tem de ir procurar.
Onde Fica a Aba Docs
Abra Orbit, clique no projeto e escolha Docs no grupo Overview na barra de abas do projeto.
Não há nada a configurar. Se o projeto tiver um repositório ligado com um README na sua raiz, a aba renderiza-o.
Qual Ficheiro É Apresentado
Orbit obtém o README do ramo predefinido do repositório ligado.
No GitHub tenta vários nomes convencionais pela ordem: README.md, readme.md, README.MD, README e readme.txt, usando o primeiro que existir. No GitLab e Bitbucket procura README.md.
Apenas a raiz do repositório é verificada. Um README dentro de um subdiretório, incluindo o diretório raiz de uma aplicação monorepo, não é detetado.
O conteúdo é colocado em cache durante aproximadamente cinco minutos. Envie uma alteração para o seu README e a aba continuará a mostrar o texto antigo brevemente. Isto é esperado; aguarde e recarregue em vez de assumir que a alteração não foi concluída.
O Que Renderiza
O README é renderizado como markdown: títulos, listas, tabelas, ligações, código inline e blocos de código cercado tudo se apresenta como esperado.
Os caminhos de imagem relativos dentro de um README apontam para o repositório, não para o KPanel, pelo que as imagens que funcionam no site do seu fornecedor podem não ser resolvidas aqui. Se uma imagem for importante, utilize um URL absoluto.
Estados Vazios
Dois estados substituem o conteúdo quando não há nada para mostrar:
- Nenhum repositório ligado, com um botão Connect repository. Ligue um primeiro: consulte Connecting a GitHub Repository, Connecting a GitLab Repository ou Connecting a Bitbucket Repository.
- Nenhum README encontrado, solicitando que adicione
README.mdà raiz do seu repositório, com uma ligação para criar um no seu fornecedor.
Ambas as ligações apontam para o fornecedor para que possa agir imediatamente, e a vista populada tem uma ligação View on para o próprio ficheiro para quando quiser editá-lo.
Escrever um README Vale a Pena Renderizar
Como esta aba fica ao lado do histórico de implementações, o README mais útil para um projeto Orbit é um operacional. Alguém abre-a porque acaba de receber o projeto e precisa de mudar algo com segurança.
Uma estrutura que funciona:
O que isto é. Um parágrafo. O que o projeto faz e a quem serve.
Executá-lo localmente. Os comandos exatos, incluindo o gestor de pacotes. pnpm install && pnpm dev é melhor do que um parágrafo a descrever a mesma coisa.
Variáveis de ambiente. Quais existem e para que serve cada uma. Nunca os valores: esses pertencem às variáveis de ambiente do projeto, não a um ficheiro no repositório. Consulte Environment Variables in Orbit.
Como implementa. Qual é o ramo de produção, se as etiquetas implementam e quais são as restrições em vigor. Aponte para a aba Orbit Deployment Pipeline em vez de a duplicar, porque a aba não pode ficar desatualizada e o seu README pode.
Como reverter. Duas frases e uma ligação para Rolling Back a Deployment. Esta é a coisa de que as pessoas precisam no seu pior momento, e deve estar onde procurarão.
Quem é o proprietário. Uma equipa ou uma pessoa. Os projetos ultrapassam as pessoas que os estabeleceram.
Nunca coloque credenciais num README. Uma cadeia de ligação, uma chave de API ou uma palavra-passe confirmada para um repositório está no histórico permanentemente, e eliminá-la numa confirmação posterior não a remove. Se aconteceu, rode a credencial em vez de tentar limpar o histórico.
Adicionar um Crachá de Estado Dinâmico
Como o README é renderizado aqui e no seu fornecedor, vale a pena adicionar um crachá de estado de implementação. Orbit publica um para cada projeto.
Abra Settings e procure o cartão Status badge. Apresenta uma pré-visualização dinâmica e três botões de cópia: o URL do crachá, um fragmento markdown e um fragmento HTML. Cole o markdown no topo do seu README.
O crachá é um pequeno SVG que relata o estado atual do ambiente de produção do projeto: deployed, building, failed, queued ou no deployments. Não precisa de autenticação, por isso renderiza para qualquer pessoa que leia o repositório, e apontam para o projeto no KPanel.
Isto dá-lhe um README que mostra, à primeira vista, se a produção está atualmente saudável. É a linha de maior valor que pode adicionar a ele.
Mantê-lo Honesto
Um README que descreve uma configuração que o projeto já não tem é pior do que nenhum README, porque as pessoas confiam nele. Dois hábitos mantêm-no preciso:
- Ligue em vez de duplicar. Qualquer coisa que seja visível no KPanel, como configurações de construção, restrições e configuração de ambiente, deve ser ligada, não reafirmada.
- Atualize-o no mesmo pedido de extração. Se uma alteração mudar a forma como o projeto funciona, a alteração do README pertence a esse pedido de extração, não a uma limpeza posterior.
Resolução de Problemas
A aba mostra uma versão antiga. O cache de cinco minutos. Aguarde e recarregue.
Nenhum README encontrado, mas há um. Verifique se está na raiz do repositório e nomeado README.md. No GitLab e Bitbucket o nome tem de corresponder exatamente.
O repositório está ligado mas a aba diz que não está. A ligação pode ter perdido acesso, por exemplo se a integração foi removida no lado do fornecedor. Religue-a a partir das definições do projeto.
As imagens não carregam. Os caminhos relativos não são resolvidos aqui. Utilize URLs absolutos.
O crachá mostra nenhumas implementações. O ambiente de produção nunca teve uma implementação bem sucedida. Implemente uma vez e atualiza.
Para Onde Ir a Seguir
- Orbit Deployment Pipeline, a versão dinâmica do que um README normalmente tenta descrever.
- Orbit Project Settings para o crachá de estado e o resto da configuração.
- Environment Variables in Orbit para os valores que um README nunca deve conter.