Estrutura de diretórios e arquivos do Axe

A sua instalação do Axe é composta de uma série de pastas e de arquivos, que devem seguir uma estrutura específica refletida no seu arquivo de configuração geral (axe_config.php).

Vamos imaginar que você descompactou o Axe no seu servidor, no diretório /users/fulano/www/blog. No primeiro nível, logo após a descompactação, você verá os 4 diretórios básicos do Axe:

  • /users/fulano/www/blog/axe
  • /users/fulano/www/blog/axethemes
  • /users/fulano/www/blog/axepreview
  • /users/fulano/www/blog/links

Para maior clareza, a partir de agora vamos nos referir a eles apenas pelos nomes (ou seja: axe, axethemes, axepreview e links).

Além dos 4 diretórios acima, a operação do Axe criará junto a eles mais arquivos e diretórios: o feed, o index, as tags e, em um diretório criado para cada ano, os posts em HTML.

Os 4 diretórios básicos do Axe

Os 4 diretórios básicos são criados no momento da descompactação do Axe na pasta em que você vai criar seu blog. Eis as suas funções:

  • axe: armazena o Axe em si (executáveis, bibliotecas e configuração), bem como os arquivos de dados que geram o conjunto de posts, tags, indexes, feed e sitemap a cada rebuild.
  • axethemes: abriga um ou mais temas, que são diretórios contendo o formato do index, dos posts e dos feeds, bem como complementos na forma de estilos CSS, imagens e mais.
  • axepreview: diretório onde são gravadas as versões preliminares de posts para visualização pelo autor, sem publicação.
  • links: diretório para compatibilidade com URLs numéricas (estilo "? p=999") de blogs importados do WordPress.

Estrutura do diretório axe

O diretório axe é o mais importante para o ciclo de vida do seu blog, e no conteúdo dele se destacam:

  • axe.php - é o executável pelo qual você passará, através dos parâmetros do axe.php, todos os seus comandos de publicação e administração do blog.
  • axe_config_exemplo.php - é o exemplo de arquivo de configuração do Axe, que você deve copiar para axe_config.php, no mesmo diretório, e editar de acordo com os dados do seu blog e servidor.
  • staging - é onde você deve gravar seus arquivos-texto de entrada, que serão pré-publicados pelo comando axe.php -d
  • drafts - é onde o Axe armazena os posts pré-publicados pelo comando axe.php -d, prontos para serem pré-visualizados, publicados ou atualizados usando os parâmetros -v, -P e -U do Axe.
  • descriptors - é onde os arquivos de dados correspondentes aos posts e tags são armazenados e catalogados internamente pelo Axe. Os arquivos HTML publicados não residem aqui, e sim no diretório principal do seu blog (no nosso exemplo, /users/fulano/www/blog)
  • plugins - é onde são armazenados os plugins (ainda não documentados).
  • authors - é onde você pode armazenar arquivos descritivos dos autores do seu blog. Por exemplo, se um post tiver como autor "Augusto César Campos", e neste diretório constar um arquivo augusto-cesar-campos.html, o conteúdo dele ficará disponível para exibição junto ao texto, caso o seu tema faça uso da variável de exibição %%POSTBIO%%.

Estrutura do diretório axethemes

Dentro do seu diretório axethemes vem pré-instalado o tema Panzer, criado especificamente para o Axe, com recursos simples de tipografia, uma coluna lateral direita, um cabeçalho e um rodapé.

Ele foi construído para adaptar-se automaticamente a larguras comuns de desktops, smart TVs, tablets e smartphones, e está à sua disposição para edição.

Comece pelo arquivo panzer/footer.php, que é onde estão definidas tanto a barra lateral quanto o rodapé. Não há problema em remover as menções ao Axe que vêm pré-instaladas, a licença open source do Axe permite ツ

As definições de estilo estão todas no arquivo panzer/css/style.css, e as referências ao conteúdo dos seus posts e aos parâmetros do seu blog são feitas por meio das variáveis de exibição, sempre apresentadas entre 2 pares de sinais de percentual. Exemplo: %%POSTAUTHOR%%

Você pode criar outros temas, armazenando-os em diretórios vizinhos ao panzer, dentro do axethemes. Não esqueça de editar o arquivo axe/axe_config.php para ativá-los.

Recomenda-se não editar o tema panzer mantendo-o no mesmo diretório original, pois um upgrade ou reinstalação do Axe irá sobrepor as suas alterações. Mude o seu nome, ou copie-o.

Se os seus temas ficarem legais e você desejar disponibilizá-los sob uma licença open source, entre em contato informando a URL onde os interessados podem encontrá-lo, juntamente com uma screenshot correspondente!

O arquivo de configuração do Axe

O arquivo axe/axe_config.txt não vem incluído na instalação do seu Axe, mas você pode (e deve) copiar o arquivo axe/axe_config_exemplo.txt para que ele se torne o axe/axe_config.txt que você irá editar para fazer o seu blog funcionar.

Se tudo correr bem, este é o único arquivo (além dos seus posts, claro) que você irá precisar editar para fazer o seu blog funcionar.

Trata-se de um arquivo em PHP, portanto cuidado para preservar a sua sintaxe.

Veremos a seguir cada uma das opções do arquivo, com comentários.

Título, descrição breve e a URL de uma imagem para servir de ícone do blog:

$blogparms["BLOGTITLE"] = 'Meu Blog';
$blogparms["BLOGMOTTO"] = "Testando o CMS AXE... e aprovando";
$blogparms["BLOGLOGO"] = "http://www.seu-site.com/img/bloglogo.png";

URL da raiz do blog, terminando com uma barra:
$blogparms["BLOGURL"] = 'http://seu-site.com/blog/';

Diretório em que está o executável axe.php:
$axedir='/users/fulano/www/blog/axe/';

Dentro do diretório acima precisam existir os diretórios a seguir:

  • staging - é onde você grava os arquivos-texto de entrada contendo os seus posts, em txt puro ou com HTML.
  • drafts - onde o Axe grava os posts pré-publicados, prontos para preview, postar ou atualizar.
  • descriptors - onde o Axe grava os arquivos de dados correspondentes aos posts já publicados.

Twitter do blog, sem @
$blogparms["BLOGTWITTER"] = 'blogtwitter';

URL para acesso externo ao feed
$blogparms["FEEDURL"] = 'http://seu-site.com/blog/feed.xml';

Dados de identificação do autor do blog: nome, URL, twitter (sem @)
$blogparms["BLOGOWNER"] = 'Fulano de Tal';
$blogparms["BLOGOWNERURL"] = 'http://url-do-dono.com/';
$blogparms["BLOGOWNERTWITTER"] = 'donotwitter';

Quantidade de posts no feed, e de posts e de destaques na capa
$blogparms["NUMPOSTSFEED"] = '10';
$blogparms["NUMPOSTSCOVER"] = '10';
$blogparms["NUMFEATSCOVER"] = '2'; // numero de destaques na capa

(observação: nem todo tema diferencia destaques e posts)

Diretório dos temas no servidor
$blogparms["THEMESDIR"] = '/users/fulano/www/blog/axethemes/';

Caminho web dos temas (em relação à raiz do blog). Começa sem e termina com /
$blogparms["THEMESPATH"] = 'axethemes/';

Pasta do tema do blog (dentro do THEMESDIR/THEMESPATH)
$blogparms["THEME"] = 'panzer/';

Diretório-base dos plugins
$blogparms["PLUGINSDIR"] = $axedir.'plugins/';

Diretório-raiz do blog, onde constam os posts publicados em HTML, os indices, tags e feed, bem como os subdiretórios axe e axethemes:
$blogparms["POSTSDIR"] = '/users/fulano/www/blog/';

Caminho web da raiz até o diretório de posts. Começa sem "/" e termina com "/"
O caso normal é esta variável ficar vazia. //TO-DO: documentar o uso.
$blogparms["POSTSURLPREFIX"] = '';

Diretório onde serão gravados os previews (em HTML) de posts, gerados pelo axe.php -v
$blogparms["PREVIEWDIR"] = '/users/fulano/www/blog/axepreview/';

# A URL completa do diretório de previews. Termina com "/"
$blogparms["PREVIEWSBASEURL"] = 'http://seu-site.com/blog/axepreview/';

Idioma, verbosidade e localização. Na dúvida, não altere.
$blogparms["BLOGLOCALE"] = 'pt_BR';
error_reporting(E_ALL ^ E_NOTICE ^ E_USER_NOTICE);
date_default_timezone_set('America/Sao_Paulo');

Após editar, grave-o com o nome de axe/axe_config.php e você já poderá experimentar os comandos básicos do Axe.

Os arquivos que definem o tema

Se você for editar ou alterar um tema, segue a lista dos arquivos que a versão atual do Axe suporta. Eles residem imediatamente abaixo da pasta do tema – na configuração default, eles estão em axethemes/panzer/.

Cabeçalho e rodapé HTML, aplicáveis à capa, índices e posts individuais:

  • header.php - se o seu tema tiver sidebar esquerda, insira-a aqui, juntamente com o cabeçalho.
  • footer.php - se o seu tema tiver sidebar direita, insira-a aqui, juntamente com o rodapé.

Posts da capa e índices, incluindo o de tags:

Arquivo individual do post:

  • single-body.php - o post em si
  • single-body-preview.php - uma visualização adicional incluída abaixo do rodapé no momento do preview (opcional)

Feed RSS: cabeçalho, item e rodapé

  • feed.header
  • feed.item
  • feed.footer

Comandos básicos do Axe

A comunicação entre o usuário e o Axe ocorre por meio de parâmetros do executável axe.php no seu Terminal, e é por isso que o Axe tem como requisito o acesso shell (ssh ou similar) ao servidor de hospedagem.

Para emitir os comandos, você pode chamar o axe.php pelo seu caminho completo, como no exemplo a seguir, que recriaria os índices do seu blog:

/users/fulano/www/blog/axe/axe.php -R

Outra alternativa é usar as expansões da shell, conforme a configuração da sua conta, como no exemplo:

~/www/blog/axe/axe.php -R

Ou ainda ir ao diretório do Axe e chamá-lo de lá:

cd ~/www/blog/axe
./axe.php -R

Usuários experientes certamente preferirão criar um alias ou mesmo incluir o Axe no path da sua shell.

Os parâmetros essenciais

Não esqueça de antes entender a estrutura de pastas do Axe e o ciclo de vida de um post do Axe.

Veja como comandar o Axe, com comandos curtos (exemplo: -d) e longos (exemplo: --draft):

  • axe.php -d nome.txt
    --draft: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging.

  • axe.php -v nome.php
    --preview: cria, a partir de um draft gerado pelo axe.php -d, uma versão completa do post em HTML para conferência na pasta de previews, mas não a publica. A URL para que ela possa ser acessada pelo autor é exibida na tela.

  • axe.php -P nome.php
    --post: publica um post em HTML puro a partir de um draft gerado pelo axe.php -d, e atualiza o index, as tags, o sitemap e o feed.

  • axe.php -U nome.php
    --update: atualiza um post a partir de um draft gerado pelo axe.php -d, e atualiza o index, as tags, o sitemap e o feed. O arquivo de entrada que gera um draft de atualização tem requisitos especiais: incluir as variáveis @@POSTTIME e @@POSTNAME correspondentes à publicação inicial. Elas podem ser geradas automaticamente, veja na documentação sobre ciclo de vida de um post do Axe os detalhes sobre o acesso rápido ao fonte de um post para atualização.

  • axe.php -X /AAAA/MM/nome.html
    --delete: apaga um post a partir da sua URL relativa (/ano/mes/nome.html), e atualiza o index, as tags e o feed.

  • axe.php -e
    --feed: força atualizar o feed, mesmo sem ter publicado ou atualizado nada.

  • axe.php -R
    --rebuild: força atualizar o index, as tags, o sitemap e o feed, mesmo sem ter publicado ou atualizado nada.

  • axe.php -L
    --catalogs: para manutenção. Força a recriação, a partir dos posts arquivados, os catálogos internos de posts e de tags, usados para fazer os rebuilds.

  • axe.php -m
    --map: Atualiza apenas o sitemap.

  • axe.php -M
    --monthly: Atualiza apenas os índices mensais (archive*.html).

Os parâmetros modificadores

Alguns dos parâmetros essenciais do Axe, acima, aceitam modificadores, na forma de parâmetros adicionais. Por exemplo, se você quiser que o comando de rebuild atualize todos os índices e posts do blog, mesmo nos casos em que ele notar que já estão atualizados, pode trocar o parâmetro -R pelo parâmetro -Rf ou -R --force

Veja a lista de modificadores:

  • -f
    --force: força o rebuild a atingir todos os arquivos, e não apenas os que precisam de atualização.

  • -i
    --indexonly: Ao chamar 'axe.php -Ri', será feito um rebuild completo de todos os índices (index*.html, tag-*.html, archive*.html, sitemap-axe.xml e o feed rss), mas não dos arquivos de posts individuais (que também seriam reconstruídos no caso de um 'axe.php -Rf').

  • -q
    --quiet: reduz as mensagens exibidas pelo Axe no Terminal.

  • -t
    --talkative: aumenta a quantidade de mensagens exibidas pelo Axe no Terminal.

  • -n
    norebuild: usado em conjunto com os comandos de post, update ou delete, impede que os índices, tags e feeds sejam atualizados automaticamente ao final da operação. Eles ficarão desatualizados, lembre-se de comandar um rebuild logo depois.

  • -o
    --noold: usado em conjunto com o comando de draft, impede que o arquivo-texto de entrada seja movido automaticamente para a pasta old ao final da operação.

  • -1
    --nofirstimage: não usa a primeira ilustração do post como um ícone para o mesmo (veja os detalhes no exemplo do arquivo de entrada).

  • axe.php -r
    --strict: esta opção1 desabilita qualquer significado especial para as 2 primeiras linhas do arquivo txt de entrada, que passam a ser meras linhas do corpo de texto. Ao usá-la, o título e as tags do post passam a ter de ser definidos com as linhas @@POSTTITLE: e @@POSTTAGS: ao final do arquivo txt de entrada.

  • axe.php -h
    --hereconf: Permite executar um Axe instalado em outro diretório, e fazê-lo ler o axe_config.php do diretório corrente, e não do diretório em que o Axe reside. Casos de uso: múltiplas instalações do Axe no mesmo ambiente, ou Axe instalado fora da árvore de diretórios do servidor web.

Combinando parâmetros

Além de poder combinar parâmetros essenciais aos parâmetros modificadores, é possível combinar o parâmetro do comando draft (-d) aos dos comandos preview (-v), post (-P) e update (-U).

Exemplos:

  • axe.php -dv nome.txt
    draft+preview: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging, e cria uma versão completa do post em HTML para conferência na pasta de previews, sem publicá-la. A URL para que ela possa ser acessada pelo autor é exibida na tela.

  • axe.php -dP nome.txt
    draft+post: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging, gera o post correspondente em HTML e o publica, atualizando index, tags, sitemap e feed.

  • axe.php -dPn nome.txt
    draft+post+norebuild: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging, gera o post correspondente em HTML e o publica, mas sem atualizar index, tags, sitemap e feed.
 
  1.  Criada por sugestão do Aurélio Jargas, autor do filtro txt2tags