Uso do Jekyll para documentação de projetos

Added by Rafael Pezzi about 3 years ago

Temos pensado em reestruturar o site do CTA e pensei que talvez o Jekyll pode algo para entrar no portfólio de ferramentas de documentação de projeto. Não para substituir o site todo, mas quem sabe para projetos individuais ou grupos de projetos correlacionados. A propósito, a capa do site do CTA foi feita com o Jekyll.

O Jekyll é uma ferramenta para criação de sites em geral, com temas e modelos bem variados. Isso pode permitir que cada projeto escolha a melhor forma de se apresentar.

Alguns sites com temas livres:

Alguns temas são mais complexos e baseados em HTML5, porém muitos seguem proposta original do Jekyll de apenas interpretar markdown. Havendo interessados, podemos fazer uma oficina de introdução ao Jekyll e pensar em uma maneira de integrá-lo no CTA.


Replies (8)

RE: Uso do Jekyll para documentação de projetos - Added by Marina de Freitas about 3 years ago

Acho muito importante buscarmos ferramentas que não sejam o site do CTA. Temos nos disposto a ensinar a arte da documentação de projetos por aí a fora, logo precisamos de uma ferramenta mais universal (Conversamos bastante sobre isso com o Dorn, do famOS, no GOSH).

Acho aconselhável fazermos uma oficina, não é sustentável que só uma pessoa do CTA saiba alterar a página. Além disso, já serve como um teste para saber se é razoável sugerir esta ferramenta como padrão.

RE: Uso do Jekyll para documentação de projetos - Added by Rafael Pezzi about 3 years ago

Oi Marina, não acho que teremos uma ferramenta padrão para documentar projetos e criar seus sites, mas acho que o Jekyll enriquece o porfólio de ferramentas.

Oficina de Jekyll - Added by Rafael Pezzi about 3 years ago

Está no ar o material preliminar da oficina de Jekyll: http://lief.if.ufrgs.br/~pezzi/Curso_Jekyll/

Tem alguns exercícios para aquecer. O Jan se dispôs a ser monitor e poderá ajudar presencialmente no CTA.

O material completo das atividades 3 a 5 serão disponibilizados durante o encontro presencial, em data a ser definida para meados de Junho.

RE: Uso do Jekyll para documentação de projetos - Added by Marina de Freitas about 3 years ago

Dúvida

No exercício 2, ao digitar " ./atualiza.sh ", retorna

-bash: ./atualiza.sh: No such file or directory

Porém, a página foi atualizada corretamente, como pode ser visto na página

Comentário

No exercício 2, é sugerido usar o editar nano, onde só é possível salvar arquivo sendo sudo (foi isso que encontrei nos tutoriais por aí). Porém não posso ser sudo na minha conta do lief, logo não consegui criar o texto, e teoricamente ninguém que usar sua conta no lief conseguirá.
Obs.: resolvi com emacs.

Minha capivara não foi :(

Tentei escrever uma capivara na página, mas saiu toda torta

Ela não é torta:

M
/)-─- /)
  _/    \
/    O  O
|      V |
|     __ ノ  
U ̄U ̄ ̄U U

RE: Uso do Jekyll para documentação de projetos - Added by Rafael Pezzi about 3 years ago

Marina,

Se está fazendo as modificações diretamente no lief, dentro no public_html, não é necessário sincronizar. Assim sendo, o passo de sincronização deste exercício está inconsistente, não deveria estar ali. Agora foi ajustado. Obrigado por relatar.

Rafael

RE: Uso do Jekyll para documentação de projetos - Added by Marina de Freitas about 3 years ago

Comentários sobre a Oficina

Achei a oficina bem proveitosa!Quebrou uma inércia que eu tinha em relação a edição de sites.
Porém, sugeriria que os primeiros passos da atividade 3, Instalação e primeiros passos, fossem movidos para exercícios preparatórios. Os comandos apt-get podem levar muito tempo, principalmente se o sistema estiver sendo rodado por pen-drive. Acredito que os seguintes passos devem ser movidos:

Atualize os pacotes do seu sistema:

sudo apt-get update
sudo apt-get upgrade

Instale as dependências do Jekyll

sudo apt-get install ruby-full build-essential

Instale o Jekyll e o Bundler usando RubyGems

$ gem install jekyll bundler

RE: Uso do Jekyll para documentação de projetos - Added by Rafael Pezzi about 3 years ago

Atualizei a oficina para atender a sugestão da Marina. Agora a atualização dos pacotes e instalação do Jekyll está junto dos exercícios preparatórios. Também coloquei um aviso para indicar que a atualização dos pacotes do TropOS rodando em pendrive pode levar algumas horas. Eis um resumo do material de hoje:

Para conhecer detalhes do funcionamento e possíveis ajustes do Jekyll consulte sua documentação oficial.

Fazendo alterações no tema - Added by Rafael Pezzi about 3 years ago

Por padrão o Jekyll e o bundle buscarão no repositório Ruby Gems os temas e plugins necessários para criação do seu site. O tema padrão do Jekyll é chamado mínima, como pode ser visto no arquivo _config.yml. Para fazer modificações no tema você deverá copiar os arquivos do tema para o diretório do projeto. Uma vez copiados ali, eles terão prioridade frente aos arquivos da localização padrão em /var/lib/gems.

1. Descubra onde está instalado o tema padrão:

$ bundle show minima
/var/lib/gems/2.1.0/gems/minima-2.1.1

2. Copie os arquivos para o diretório do projeto. Por exemplo

$ cp -r /var/lib/gems/2.1.0/gems/minima-2.1.1/* ~/projeto_1/

3. Faça suas modificações nos arquivos copiados em _includes e _layouts e gere seu site.

(1-8/8)