stacy
v2.0.0
Stacy é um gerador de sites que combina conteúdo de Contentful CMS com modelos Handlebars para criar as páginas do site.
Stacy combina os tipos de conteúdo de entrada do Contentful com os modelos Handlebars no projeto do seu site em um relacionamento um para um - há um modelo para cada tipo de entrada definido no seu modelo de conteúdo . Existem dois tipos de entradas do ponto de vista de Stacy: entradas de página e entradas de módulo . Uma entrada de página combinada com seu modelo produz uma única página de site em um URL exclusivo. As entradas do módulo podem ser incluídas em páginas e outros módulos usando os campos de referência do Contentful para criar partes reutilizáveis de conteúdo ou simplesmente para fornecer estrutura de conteúdo e modelos, dividindo-os em partes menores.
O que torna Stacy diferente de muitos geradores de sites estáticos existentes é que ele oferece suporte à publicação automática do site em um bucket S3 na Amazon Cloud, de onde pode ser veiculado na Internet. Stacy implanta infraestrutura especial na Amazon Cloud que pode ser conectada ao Contentful por meio de sua funcionalidade Webhooks. Quando o conteúdo é atualizado em seu espaço Contentful, a infraestrutura do seu site implantada pela Stacy na Amazon Cloud é notificada e regenera e republica automaticamente apenas as páginas do seu site que são afetadas pela atualização. Nenhuma regeneração e reimplantação manual do site é necessária.
Ao usar Stacy, seu site é um projeto NPM geralmente verificado em um repositório git para controle de versão. O projeto inclui modelos do Handlebars e conteúdo estático (como folhas de estilo CSS, imagens usadas no design do site, fontes, etc.), enquanto o conteúdo do site reside no espaço Contentful. A partir do projeto do site, os desenvolvedores do site usam a ferramenta de linha de comando Stacy para desenvolver, publicar e republicar o site. Depois que o site é publicado na Amazon Cloud, os autores do conteúdo trabalham apenas com Contentful UI.
Consulte Criando um site com Stacy para obter um tutorial/passo a passo detalhado.
Primeiro, você precisa de um espaço com conteúdo para o conteúdo do seu site. Depois de fazer isso, você pode criar um novo projeto para o seu site.
Certifique-se de ter o Node.js versão 10.16.3 ou mais recente instalado junto com o npm. Se você pretende publicar o site na Amazon Cloud, também precisará do AWS CLI instalado.
Comece instalando Stacy globalmente:
npm install -g stacy
Em seu espaço Contentful, vá para Configurações do espaço→Chaves de API e adicione uma chave de API em Content delivery/preview tokens . Nota Valores de token de acesso do Space ID e da API Content Delivery que você usará para conectar seu ambiente Stacy ao seu espaço Contentful.
Agora você pode gerar o projeto inicial para o seu site:
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
Isto criará um novo diretório de projeto chamado “mywebsite” no diretório atual. O valor "mywebsite" é conhecido como ID do site . Use um valor diferente que identifique seu site. O valor deve ser compatível com URL (letras minúsculas, dígitos e travessões).
No diretório do seu projeto, coloque o conteúdo estático em /static (ele é copiado para o seu site como está) e coloque seus modelos de entrada em /templates . O nome do arquivo de modelo (sem a extensão) deve corresponder exatamente ao tipo de conteúdo de entrada correspondente em seu modelo Contentful Content . Em /templates , os arquivos de modelo podem ser organizados em subpastas. No entanto, os nomes dos arquivos devem ser exclusivos em todas as subpastas porque são usados para corresponder exclusivamente os modelos aos tipos de conteúdo de entrada (as subpastas em /templates não desempenham nenhuma função).
Nota: Normalmente, um modelo, combinado com o conteúdo de uma entrada, produz HTML. Se precisar produzir algum outro tipo de conteúdo, você pode adicionar uma extensão ao nome do modelo. Por exemplo, page.hbs produz HTML. Para produzir texto simples, use page.txt.hbs . Isso também significa que page.hbs e page.html.hbs são iguais.
Agora você pode executar seu site localmente para fins de desenvolvimento:
stacy serve
Você pode ver seu site em http://localhost:8080/ . Depois de editar qualquer modelo, conteúdo estático ou conteúdo no Contentful, basta recarregar a página.
Para parar o servidor web local Stacy, use Ctrl+C .
Execute stacy --help para ver outros comandos disponíveis.
Você pode fazer check-in do conteúdo do diretório do seu projeto em um repositório git, como GitHub ou Bitbucket.
Dentro de seus modelos, todos os campos de entrada estão disponíveis pelo Field ID conforme definido em seu modelo de conteúdo . Você pode referenciá-los diretamente em seu modelo. Por exemplo:
Isso gerará o valor do campo caption da entrada. Observe que é o Field ID que é usado aqui e não o campo Name .
Stacy adiciona alguns ajudantes especiais que você pode usar em seus modelos:
module <reference field> - Inclui a entrada do módulo referenciada pelo campo Tipo de referência. Por exemplo, dado que você possui um campo com paragraphs de identificação e é uma lista de referências:
asset <asset field> - Inclui o ativo referido, como uma imagem. Por exemplo:
Atualmente, apenas recursos de imagem são suportados, para os quais uma tag HTML <img> é renderizada.
assetSrc <asset field> - Obtenha o URL do ativo. Por exemplo:
assetTitle <asset field> - Obtenha o título do ativo. Por exemplo:
markdown <long text field> - Renderiza o campo de texto longo do Markdown. Por exemplo:
Observe os colchetes necessários aqui porque o auxiliar gera HTML que não precisa ser escapado.
richText <rich text field> - Renderiza o campo rich text. Por exemplo:
Tal como acontece com markdown , observe os colchetes triplos.
json <field> - Saída da representação JSON com conteúdo interno do campo. Por exemplo:
Este auxiliar pode ser útil para diagnosticar problemas.
Conforme mencionado acima, há um relacionamento um-para-um entre os tipos de conteúdo que você define no modelo e nos modelos de conteúdo do seu espaço Contentful.
Nota: A rigor, você pode ter mais de um modelo para um determinado tipo de conteúdo para permitir a geração de diferentes tipos de arquivos para a mesma entrada de conteúdo. Por exemplo, para module de ID do tipo de conteúdo, você pode ter os modelos module.html.hbs e module.xml.hbs . O primeiro modelo produzirá um arquivo HTML para a entrada e o segundo produzirá um arquivo XML.
Ao definir um tipo de conteúdo, observe o identificador da API (também conhecido como ID do tipo de conteúdo ). O arquivo de modelo para o tipo de conteúdo deverá ter o mesmo nome (mais a extensão).
Há um requisito para tipos de conteúdo para entradas de página (em oposição às entradas de módulo): um tipo de conteúdo de página deve definir um campo de slug obrigatório. O valor do campo determinará o nome do arquivo gerado quando a entrada do conteúdo for combinada com o template correspondente. Por exemplo, se o valor do slug para uma entrada de página for "index", a página gerada será "/index.html". Se o slug for "more/terms", a página será "/more/terms.html". E assim por diante.
Por padrão, o ID do campo slug deve ser slug . O ID pode ser substituído no arquivo stacy.json do projeto. Além de tornar o campo slug obrigatório na definição do tipo de conteúdo, também é recomendado associar um validador de padrão de correspondência customizado a ele para garantir o formato específico do valor do campo. A expressão regular para o validador pode ser ^w[w-]*(/w[w-]*)*$ .
Quando estiver pronto para implantar seu site na AWS, primeiro você precisará configurar a infraestrutura Stacy em sua conta AWS. Você deve executar várias etapas antes de fazer isso:
Crie o bucket S3 de destino. É aqui que seu site será publicado e de onde será veiculado (provavelmente via CloudFront). Como alternativa, você pode usar um bucket que já possui (Stacy também oferece suporte à publicação em uma subpasta no bucket de destino).
Se você ainda não o fez, crie um bucket S3 que Stacy usará para fazer upload do pacote de funções Lambda do editor. A função Lambda do editor é a parte que responde aos eventos de publicação e cancelamento de publicação do Contentful e atualiza as páginas e ativos relevantes no bucket S3 de destino.
Crie o pacote do editor:
stacy build-publisher
Isso criará o pacote de funções do editor Lambda em seu projeto em /build/stacy-mywebsite-publisher.zip . Faça upload deste arquivo para o bucket S3 de funções do Lambda.
stacy new de Stacy gerou um modelo CloudFormation para o ambiente AWS e o salvou em seu projeto em /misc/cfn-template.json . Você pode revisá-lo e personalizá-lo, se necessário. Caso contrário, vá em frente e crie a pilha Stacy para o seu site na sua conta AWS.
Depois que a pilha do CloudFormation for criada, você precisará ajustar a política do bucket S3 de destino para permitir que o editor Stacy publique nele o conteúdo do site gerado. A política do bucket pode incluir algo como o seguinte:
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} Na política acima, substitua o ARN da função de editor Stacy pelo valor que você pode encontrar no parâmetro de saída PublisherRoleArn da pilha do CloudFormation e o nome do bucket pelo nome do bucket do site de destino (o bucket ao qual a política é aplicada).
Agora você precisa preparar seu ambiente de desenvolvimento para publicação. Abra e edite o arquivo .env no projeto do seu site. Nele, defina todas as variáveis AWS_* com os valores corretos. Observe que você pode encontrar o valor da variável AWS_PUBLISH_EVENT_SOURCE_MAPPING no parâmetro de saída PublishEventSourceMappingId da pilha CloudFormation.
Depois que seu arquivo .env estiver configurado corretamente, você poderá publicar seu site usando:
stacy publish
Uma última etapa de configuração é configurar um webhook em seu espaço Contentful para chamar o editor Stacy em eventos de publicação e cancelamento de publicação . Na sua conta AWS, no serviço API Gateway, encontre a API criada para você por Stacy. Existe apenas um método POST /publish no estágio prod da API. Observe seu Invoke URL .
Além disso, vá para a seção Chaves de API e anote o valor da chave de API criada para Stacy.
No seu espaço Contentful, vá para Configurações do espaço→Webhooks e adicione um webhook. Coloque a URL de invocação da API Gatwey no campo URL (deixe o método POST ). Em seguida, escolha a opção Selecionar eventos de acionamento específicos na seção Gatilhos . Marque as caixas de seleção Publicar e Cancelar publicação nas linhas Entrada e Ativo (4 caixas de seleção marcadas no total).
Na seção Cabeçalhos , clique em Adicionar cabeçalho secreto . Coloque "X-API-Key" no campo Chave e no campo Valor coloque a chave API do API Gateway.
Depois de salvar este webhook, a publicação e remoção de entradas e ativos no Contentful acionará o editor na configuração da AWS e está tudo pronto!
