Publicando com o GitHub Pages

Parar publicar um site ou documentação com o GitHub Pages só precisa de 3 etapas:

1. Crie um novo repositório ou use um repositório existente
2. Envie um arquivo de Markdown através da interface da web ou pelo git commit.
3. Ative as Páginas do GitHub através das configurações do seu repositório.

Pronto agora tem um site!

Se quiser testar:

1. Crie um novo repositório
   
   

   Imagem Novo Repositorio Git Hub

2. Envie um arquivo de Markdown. Se você marcou para adicionar o README.md esse já é o arquivo Markdown enviado.
   

   Repositorio com o README.MD

3. Para ativar clique em Settings e ative as Páginas do GitHub.
   1. Altere a opção Source do Github Pages para: master branch
      

      Configuração Github Pages

   2. Ao salvar dentro dessas opções vai aparecer o link da pagina do seu repositório, no nosso exemplo temos nosso site publicado na url https://mariojp.github.io/page/
      

      Link para sua pagina

Existem outra opção para publicação como escolher no Source: master branch /docs folder onde voce deve criar uma pasta docs que será a raiz da sua pagina.

Por baixo dos panos para que tudo isso funcione o os arquivos de Markdown são renderizados pelas Páginas GitHub e o arquivo README.md é utilizado como o índice do site se você não tiver um index.md (ou index.html).

Você ainda pode especificar um um tema no menu settings -> Github Pages na opção: Theme chooser.

Se não houver tema escolhido é definido um tema padrão mínimo que corresponda à aparência do Markdown padrão no GitHub. Com a escolha de um tema o Github Pages adiciona um arquivo _config.yml que contem a configuração do tema.

Para quem quiser ir mais alem boa parte da magica é feita com uso do Jekyll (https://jekyllrb.com).

“Para que o processo de criação das páginas do GitHub possa ser o mais transparente e personalizável possível, todos os recursos acima são implementados como plugins Jekyll de código aberto, como Jekyll Opcional Front Matter, Jekyll README Index, Jekyll Padrão Layout e Jekyll Títulos de Cabeçalhos”. (Traduzido da documentação)

Não perca tempo e teste agora ou coloque documentação no seu site.