Blarg - Manual do usuário do Blosh

O Blosh é um compilador de blogs e websites estáticos escrito em shell script.

O Blosh lê arquivos de texto escritos no formato markdown e gera páginas HTML estáticas que podem ser publicadas em um servidor web.

Para mais informações sobre o Blosh, visite a página do Blosh na Internet.

Obtendo o Blosh

Para obter uma cópia do Blosh, visite a página do Blosh na Internet e baixe uma cópia do seu código fonte.

Lembre-se de substituir o número de versão nos exemplos a seguir pelo número da última versão disponível do Blosh:

Baixe o código fonte do Blosh:

wget https://www.arg.eti.br/blog/pages/software/blosh/blosh_1.4.tgz

Descompacte o arquivo com o código fonte:
```
tar zxvf blosh_1.4.tgz
```
Copie os arquivos executáveis para algum diretório do seu PATH:
```
sudo cp blosh-*.sh /usr/local/bin/
```

Dependências

O Blosh depende de outros programas para funcionar corretamente. Você deve ter os seguintes programas principais instalados em seu computador:

markdown
tidy
iconv

Para instalá-los em um sistema Debian ou derivado:

sudo aptitude install markdown tidy libc-bin

Preparando o repositório para o seu blog

Você deve escolher e preparar um local para armazenar os arquivos fonte dos artigos, páginas e arquivos estáticos, como imagens, que formarão o seu blog:

mkdir ~/meublog
cd ~/meublog/
blosh-init.sh

Configurando o Blosh

Para configurar o Blosh para o seu blog, edite o arquivo blosh.conf. As variáveis de configuração são as seguintes:

URL_DOMAIN: domínio do seu blog. Exemplo: "http://www.example.org"
URL_ROOT: diretório raiz do seu blog. Exemplo: "blog"
BLOG_TITLE: título do seu blog. Exemplo: "Meu blog"
BLOG_DESCRIPTION: descrição do seu blog. Exemplo: "Apenas mais um blog na Internet"
BLOG_FOOTNOTE: nota de rodapé do seu blog. Pode conter tags HTML. Exemplo: "Esta página foi gerada pelo <a href="https://www.arg.eti.br/blog/pages/software/blosh/index.html">Blosh</a>."
WORKING_AREA_DIR: diretório de trabalho. Exemplo: "./tmp"
OUTPUT_DIR: diretório de saída. Exemplo: "./output"
MENU_PAGES: páginas que serão colocadas no menu. Exemplo: "contato sobre"

Escrevendo um artigo

Para escrever um artigo, você deve criar um arquivo de texto no formato markdown dentro do diretório posts do repositório do seu blog, com a extensão .markdown:

cd ~/meublog/
blosh-new-post.sh posts/ola-mundo.markdown

Para editar o artigo, use o seu editor de texto preferido:

vi posts/ola-mundo.markdown

O formato de arquivo do artigo

O artigo deve ser escrito no formato markdown. Para conhecer o formato, visite a página do markdown na Internet.

Ao criar o seu artigo com o blosh-new-post.sh, o seu artigo será criado com o seguinte conteúdo inicial:

# title: Título do post
# date:  YYYY-MM-DD HH:MM
# tags:  lista de tags separadas por espaço
# url:   url-opcional-derivada-de-title-se-nao-especificada

Primeiro parágrafo do meu novo post.

<!-- break -->

A marca acima define o resumo do post.

Escreva o post na sintaxe do markdown.

O artigo é composto por duas seções: o cabeçalho e o corpo do artigo. As duas seções são separadas por uma linha em branco.

O cabeçalho do artigo

O cabeçalho do artigo tem o seguinte formato:

# title: Título do post
# date:  YYYY-MM-DD HH:MM
# tags:  lista de tags separadas por espaço
# url:   url-opcional-derivada-de-title-se-nao-especificada

Onde:

title: título do artigo. Exemplo: Olá, mundo!
date: data de publicação do artigo. Exemplo: 2014-07-13 22:05
tags: lista de tags do artigo, separadas por espaços. Exemplo: teste olá
url: url opcional para o artigo. Se a url não for especificada, será gerada automaticamente uma url derivada do título. Por exemplo, se o título for Olá, mundo!, a url gerada automaticamente será ola-mundo. Caso queira definir sua própria url ao invés de usar a url gerada automaticamente, especifique-a aqui. Exemplo: meu-primeiro-artigo.

O corpo do artigo

O corpo do artigo deve ser escrito no formato markdown. Para conhecer o formato, visite a página do markdown na Internet.

Você pode dividir o corpo do artigo em duas partes: somente a primeira parte será exibida nas listas de artigos e nos feeds RSS. A segunda parte será exibida somente na página do artigo completo, após a primeira parte.

Caso você queira dividir o artigo em duas partes, faça isso incluindo no local da divisão uma linha contendo somente o seguinte texto:

<!-- break -->

Caso não queira dividir o artigo em duas partes, o texto completo do artigo será usado para a primeira parte e a segunda parte será vazia.

Escrevendo uma página

Para escrever uma página, você deve criar um arquivo de texto no formato markdown dentro do diretório pages do repositório do seu blog, ou em um subdiretório dele, com a extensão .markdown:

cd ~/meublog/
blosh-new-page.sh pages/sobre.markdown

Para editar a página, use o seu editor de texto preferido:

vi pages/sobre.markdown

O formato de arquivo da página

A página deve ser escrita no formato markdown. Para conhecer o formato, visite a página do markdown na Internet.

Ao criar a página com o blosh-new-page.sh, a sua página será criada com o seguinte conteúdo inicial:

# title: Título da página
# date:  YYYY-MM-DD HH:MM
# url:   url-opcional-derivada-de-title-se-nao-especificada

Escreva a página na sintaxe do markdown.

A pagina é composta por duas seções: o cabeçalho e o corpo da página. As duas seções são separadas por uma linha em branco.

O cabeçalho da página

O cabeçalho da página tem o seguinte formato:

# title: Título da página
# date:  YYYY-MM-DD HH:MM
# url:   url-opcional-derivada-de-title-se-nao-especificada

Onde:

title: título da página. Exemplo: Sobre
date: data da última modificação da página. Exemplo: 2014-07-13 22:05
url: url opcional para a página. Se a url não for especificada, será gerada automaticamente uma url derivada do título. Por exemplo, se o título for Sobre, a url gerada automaticamente será sobre. Caso queira definir sua própria url ao invés de usar a url gerada automaticamente, especifique-a aqui. Exemplo: sobre-o-meu-blog.

O corpo da página

O corpo da página deve ser escrito no formato markdown. Para conhecer o formato, visite a página do markdown na Internet.

Compilando o seu blog

Após editar o seu blog, e antes de publicá-lo, você deve compilá-lo. Compilar o blog significa gerar páginas HTML a partir de todos os arquivos fonte de artigos e páginas e de todos os arquivos estáticos que você produziu.

Ao compilar o blog, serão geradas a página inicial do blog contendo os últimos artigos publicados, as páginas dos artigos completos, as páginas de arquivamento de artigos agrupados por tag e por data, os arquivos contendo os feeds RSS para cada tag, o feed RSS geral do blog e as páginas e demais arquivos estáticos que compõem o seu blog.

Para compilar o blog, execute o shell script blosh-compile.sh:

cd ~/meublog/
blosh-compile.sh

Ao completar a compilação, o diretório output conterá toda a estrutura de diretórios e arquivos que formam o seu blog.

Publicando o seu blog

Depois de compilar o seu blog, você pode publicá-lo em um servidor web. Para copiar o seu blog para o servidor web, use o método preferido por você.

Por exemplo, para copiar usando rsync:

rsync --delete -avz output/ www.example.com:/var/www/blog