A documentação que você está lendo agora é mantida pela comunidade BookWyrm. Qualquer um pode contribuir com a documentação.
Você pode relatar erros, sugerir melhorias, ou solicitar uma adição à documentação criando um issue no repositório da documentação.
A documentação possui seu próprio repositório GitHub. A documentação é escrita em Markdown e usamos Jinja e Python para a converter em HTML. Um plugin Jinja é usado com Crowdin para criar traduções. Todos os arquivos fonte devem ser escritos em Inglês (US).
Todos os arquivos fonte são salvos no diretório content. Cada seção tem um diretório dentro dele, com cada página sendo um único arquivo markdown.
Para criar ou editar uma nova página, você vai precisar de:
content - seja editando uma página markdown existente, ou criando uma novaSe você nunca usou git ou GitHub antes, isso tudo pode soar um tanto desafiador, mas, vamos simplificar:
git clone https://github.com/bookwyrm-social/documentation.git
Para fazer alterações:
content e faça um commit das suas alterações:
- Interface GitHub web
- GitHub Desktop
- Na linha de comando, salve suas alterações nos arquivos e execute git commitA esse ponto, você deve querer ver como suas mudanças serão mostradas quando publicadas. Veja Criando documentação localmente abaixo, para instruções sobre como pré-visualizar suas alterações.
Assim que concluir suas alterações, faça um pull request ao repositório da documentação.
Seu pull request será revisado e uma das três coisas vai acontecer:
Se pedirem para fazer alterações, você pode fazê-las localmente e fazer push das suas mudanças locais para seu fork/clone no GitHub. Isso aparecerá automaticamente na sua pull request. Avise o revisor quando terminar suas atualizações para que ele possa fazer outra revisão e, com sorte, aceitar suas mudanças.
Todas as contribuições são bem-vindas. Seria incomum que uma contribuição para a documentação fosse rejeitada imediatamente. Isso só aconteceria se seu pull request apresentasse informações erradas ou que são enganosas, sem chance de melhorias, ou se for declarado como fora de escopo.
Quando seu pull request é incorporado, a documentação é atualizada automaticamente. Pode ser necessário recarregar a página ou usar o "modo anônimo" para ver as mudanças em seu navegador.
Se estiver adicionando uma nova página, você precisará adicionar alguns metadados, e pode precisar ajustar outras páginas.
At the top of each markdown file is the "frontmatter" in yaml format:
Título: Documentação
Data: 2025-04-09
Ordem: 4
Esse exemplo mostra que a página é chamada "Documentação", deve ser a quarta página dentro de sua seção (neste caso, Contribuindo), e que a última atualização foi em 9 de Abril de 2025. Se você adicionar uma página em qualquer lugar que não seja no fim de uma seção, você vai precisar ajustar a ordem das outras páginas que aparecerem abaixo de sua nova página.
Esta seção está contida entre um par de traços triplos (---). Em markdown, traços triplos podem ser usados para indicar uma linha horizontal, no entanto, o parser de documentos do BookWyrm pode ficar confuso com isso. Se você precisar de uma linha horizontal, insira-a como código HTML diretamente com linhas vazias, acima e abaixo
<0/>
Você pode querer ver como suas alterações serão mostradas antes de enviar um pull request. O repositório da documentação inclui um script de desenvolvimento igual ao do repositório de código principal, com o mesmo nome: bw-dev. Você pode usar isso para testar como suas alterações serão mostradas.
Diferente do projeto principal, a documentação não é executada em um contêiner Docker. Se você quiser compilar o site da documentação localmente, você vai precisar instalar as dependências. É recomendado usar um ambiente virtual:
python -m venv /path/to/new/virtual/environment
source <venv>/bin/activate
python -m pip install .
Você pode ver alguns comandos disponíveis ao executar ./bw-dev <venv>. Os que você provavelmente quer, são:
Isso irá compilar arquivos markdown em arquivos html usando o script generate.py.
Quando você executar site:compile, irá gerar um grande número de arquivos no diretório site. Não os marque ou inclua em seu pull request: eles serão gerados novamente, no servidor da documentação, quando seu pull request for incorporado.
Isso roda um servidor local em http://[::1]:8080/ para que você possa ver como a documentação será apresentada.
We use ruff for linting and formatting. Ensure that you run ./bw-dev ruff before pushing your pull request if you made any changes to Python files in the documentation repository. You can try auto-fixing any linting issues with ./bw-dev ruff-fix.
Mantenha traduções alinhadas atualizando regularmente do Crowdin:
pull tanto do main, quanto do l10n_main , para eles estarem atualizados em seu repositório localmain (p. ex. chamado update_locales) e mude pare elelocale do l10n_main no seu fork: git checkout l10n_main -- localemainIdiomas para o menu dropdown de idiomas, estão listados em i18n.py. Geralmente, esperamos que um idioma atinja 70% de cobertura no Crowdin antes de adicioná-lo à lista, para evitar deixar muito conteúdo sem tradução.
Quando uma nova versão do BookWyrm é lançada, precisamos criar uma versão da documentação.
v0.x.y.generate.py, and push your new branch to the repository.generate.py file into it so they all have the new branch listed: git checkout v0.x.y generate.py. Em seguida, faça commit desta alteração, crie uma PR para fazer merge desta mudança na branch da versão na documentação, e faça merge dela. Isso garantirá que todas as páginas de todas as versões da documentação estarão listadas no menu dropdown.generate.py in the main branch last - only merges into main trigger the GitHub action to deploy to the docs web server so if you do this first, the changes in other branches will have no effect until next time you update main.