stacy
v2.0.0
Stacy es un generador de sitios web que combina contenido de Contentful CMS con plantillas de manillar para crear páginas del sitio web.
Stacy combina los tipos de contenido de entrada de Contentful con las plantillas de Handlers en su proyecto de sitio web en una relación uno a uno: hay una plantilla para cada tipo de entrada definida en su modelo de contenido . Hay dos tipos de entradas desde el punto de vista de Stacy: entradas de página y entradas de módulo . Una entrada de página combinada con su plantilla produce una única página de sitio web en una URL única. Las entradas de los módulos se pueden incluir en páginas y otros módulos utilizando los campos de Referencia de Contentful para crear piezas de contenido reutilizables o simplemente para proporcionar estructura de contenido y plantillas dividiéndolas en piezas más pequeñas.
Lo que diferencia a Stacy de muchos generadores de sitios web estáticos existentes es que admite la publicación automática del sitio web en un depósito S3 en Amazon Cloud, desde donde se puede publicar en Internet. Stacy implementa una infraestructura especial en Amazon Cloud que se puede conectar a Contentful a través de su funcionalidad Webhooks. Cuando se actualiza el contenido en su espacio Contentful, la infraestructura de su sitio web implementada por Stacy en Amazon Cloud recibe una notificación y automáticamente regenera y vuelve a publicar solo aquellas páginas de su sitio web que se ven afectadas por la actualización. No se requiere regeneración ni redistribución manual del sitio web.
Cuando usa Stacy, su sitio web es un proyecto NPM que generalmente se registra en un repositorio de Git para el control de versiones. El proyecto incluye sus plantillas de manillar y contenido estático (como hojas de estilo CSS, imágenes utilizadas en el diseño del sitio web, fuentes, etc.), mientras que el contenido del sitio web reside en el espacio Contentful. Desde el proyecto del sitio web, los desarrolladores del sitio web utilizan la herramienta de línea de comandos Stacy para desarrollar, publicar y volver a publicar el sitio. Una vez que el sitio web se publica en Amazon Cloud, los autores de contenido trabajan solo con Contentful UI.
Consulte Creación de un sitio web con Stacy para obtener un tutorial/tutorial detallado.
Primero, necesita un espacio Contentful para el contenido de su sitio web. Una vez que tenga eso, puede crear un nuevo proyecto para su sitio web.
Asegúrese de tener instalada la versión 10.16.3 o posterior de Node.js junto con npm. Si va a publicar el sitio web en Amazon Cloud, también necesitará tener instalado AWS CLI.
Comience instalando Stacy globalmente:
npm install -g stacy
En su espacio Contentful, vaya a Configuración del espacio → Claves API y agregue una clave API en Tokens de vista previa/entrega de contenido . Tenga en cuenta los valores del token de acceso de ID de espacio y API de entrega de contenido que utilizará para conectar su entorno Stacy a su espacio Contentful.
Ahora puedes generar un proyecto inicial para tu sitio web:
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
Esto creará un nuevo directorio de proyecto llamado "mywebsite" en el directorio actual. El valor "mywebsite" se conoce como ID del sitio . Utilice un valor diferente que identifique su sitio web. El valor debe ser compatible con URL (letras minúsculas, dígitos y guiones).
En el directorio de su proyecto, coloque el contenido estático en /static (esto se copia en su sitio web tal como está) y coloque sus plantillas de entrada en /templates . El nombre del archivo de plantilla (sin la extensión) debe coincidir exactamente con el tipo de contenido de entrada correspondiente en su modelo de Contenido Contentful. En /templates , los archivos de plantilla se pueden organizar en subcarpetas. Sin embargo, los nombres de los archivos deben ser únicos en todas las subcarpetas porque se utilizan para hacer coincidir de forma única las plantillas con los tipos de contenido de entrada (las subcarpetas en /templates no desempeñan ninguna función).
Nota: Normalmente, una plantilla, combinada con el contenido de una entrada, produce HTML. Si necesita producir algún otro tipo de contenido, puede agregar una extensión al nombre de la plantilla. Por ejemplo, page.hbs produce HTML. Para producir texto sin formato, utilice page.txt.hbs . Esto también significa que page.hbs y page.html.hbs son iguales.
Ahora puede ejecutar su sitio web localmente con fines de desarrollo:
stacy serve
Puede ver su sitio web en http://localhost:8080/ . Después de editar cualquier plantilla, contenido estático o contenido en Contentful, simplemente vuelva a cargar la página.
Para detener el servidor web local de Stacy, utilice Ctrl+C .
Ejecute stacy --help para ver otros comandos disponibles.
Puede registrar el contenido del directorio de su proyecto en un repositorio de git como GitHub o Bitbucket.
Dentro de sus plantillas, todos los campos de entrada están disponibles según el ID de campo definido en su modelo de contenido . Puede hacer referencia a ellos directamente en su plantilla. Por ejemplo:
Esto generará el valor del campo caption de la entrada. Tenga en cuenta que aquí se utiliza el ID de campo y no el Nombre del campo.
Stacy agrega algunos ayudantes especiales que puedes usar en tus plantillas:
module <reference field> : incluye la entrada del módulo a la que hace referencia el campo Tipo de referencia. Por ejemplo, dado que tienes un campo con paragraphs ID y es una lista de referencias:
asset <asset field> : incluye el activo al que se hace referencia, como una imagen. Por ejemplo:
Actualmente, solo se admiten recursos de imagen para los cuales se representa una etiqueta HTML <img> .
assetSrc <asset field> : obtiene la URL del activo. Por ejemplo:
assetTitle <asset field> : obtiene el título del activo. Por ejemplo:
markdown <long text field> - Representar campo de texto largo de Markdown. Por ejemplo:
Tenga en cuenta las llaves triples necesarias aquí porque el asistente genera HTML del que no es necesario escapar.
richText <rich text field> : renderiza un campo de texto enriquecido. Por ejemplo:
Al igual que con markdown , tenga en cuenta las llaves triples.
json <field> : genera una representación JSON con contenido interno del campo. Por ejemplo:
Esta ayuda puede resultar útil para diagnosticar problemas.
Como se mencionó anteriormente, existe una relación uno a uno entre los tipos de contenido que usted define en el modelo de contenido y las plantillas de su espacio Contentful.
Nota: Estrictamente hablando, puede tener más de una plantilla para un tipo de contenido determinado para permitir la generación de diferentes tipos de archivos para la misma entrada de contenido. Por ejemplo, para module de ID de tipo de contenido, podría tener las plantillas module.html.hbs y module.xml.hbs . La primera plantilla producirá un archivo HTML para la entrada y la segunda producirá un archivo XML.
Cuando defina un tipo de contenido, tenga en cuenta el identificador de API (también conocido como ID de tipo de contenido ). El archivo de plantilla para el tipo de contenido deberá tener el mismo nombre (más la extensión).
Hay un requisito para los tipos de contenido para las entradas de página (a diferencia de las entradas de módulo): un tipo de contenido de página debe definir un campo slug obligatorio. El valor en el campo determinará el nombre del archivo generado cuando la entrada de contenido se combine con la plantilla correspondiente. Por ejemplo, si el valor slug para una entrada de página es "índice", la página generada será "/index.html". Si el slug es "más/términos", la página será "/más/terms.html". Etcétera.
De forma predeterminada, el ID de campo para el campo slug debe ser slug . El ID se puede anular en el archivo stacy.json del proyecto. Además de hacer que el campo slug sea obligatorio en la definición del tipo de contenido, también se recomienda asociarle un validador de patrón de coincidencia personalizado para garantizar el formato específico del valor del campo. La expresión regular para el validador puede ser ^w[w-]*(/w[w-]*)*$ .
Cuando esté listo para implementar su sitio web en AWS, primero deberá configurar la infraestructura Stacy en su cuenta de AWS. Debes realizar varios pasos antes de poder hacerlo:
Cree el depósito S3 de destino. Aquí es donde se publicará su sitio web y desde donde se brindará servicio (probablemente a través de CloudFront). Alternativamente, puede usar un depósito que ya tenga (Stacy también admite la publicación en una subcarpeta en el depósito de destino).
Si aún no lo tiene, cree un depósito S3 que Stacy usará para cargar el paquete de funciones Lambda del editor. La función Lambda del editor es la pieza que responde a los eventos de publicación y anulación de publicación de Contentful y actualiza las páginas y recursos relevantes en el depósito S3 de destino.
Cree el paquete del editor:
stacy build-publisher
Esto creará el paquete de funciones Lambda del editor en su proyecto en /build/stacy-mywebsite-publisher.zip . Cargue este archivo en su depósito S3 de funciones Lambda.
El comando stacy new de Stacy generó una plantilla de CloudFormation para el entorno de AWS y la guardó en su proyecto en /misc/cfn-template.json . Puedes revisarlo y personalizarlo si es necesario. De lo contrario, continúe y cree la pila Stacy para su sitio web en su cuenta de AWS.
Una vez que se crea la pila de CloudFormation, debe ajustar la política del depósito S3 de destino para permitir que el editor Stacy publique el contenido del sitio web generado en él. La política del depósito puede incluir algo como lo siguiente:
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} En la política anterior, reemplace el ARN del rol de editor de Stacy con el valor que puede encontrar en el parámetro de salida PublisherRoleArn de su pila de CloudFormation y el nombre del depósito con el nombre del depósito del sitio web de destino (el depósito al que se aplica la política).
Ahora tienes que preparar tu entorno de desarrollo para la publicación. Abra y edite el archivo .env en el proyecto de su sitio web. En él, establezca todas las variables AWS_* en los valores correctos. Tenga en cuenta que puede encontrar el valor de la variable AWS_PUBLISH_EVENT_SOURCE_MAPPING en el parámetro de salida PublishEventSourceMappingId de la pila de CloudFormation.
Una vez que su archivo .env esté configurado correctamente, puede publicar su sitio web usando:
stacy publish
Un último paso de configuración es configurar un webhook en su espacio Contentful para llamar al editor Stacy sobre eventos de publicación y anulación de publicación . En su cuenta de AWS, en el servicio API Gateway, busque la API creada para usted por Stacy. Solo hay un método POST /publish en la etapa prod de la API. Tenga en cuenta su URL de invocación .
Además, vaya a la sección Claves API y anote el valor de la clave API creada para Stacy.
En su espacio Contentful, vaya a Configuración del espacio → Webhooks y agregue un webhook. Coloque la URL de invocación de API Gatwey en el campo URL (deje el método POST ). Luego elija la opción Seleccionar eventos desencadenantes específicos en la sección Desencadenadores . Marque las casillas de verificación Publicar y Anular publicación en las filas Entrada y Activo (4 casillas marcadas en total).
En la sección Encabezados , haga clic en Agregar encabezado secreto . Coloque "X-API-Key" en el campo Clave y en el campo Valor coloque la clave API de API Gateway.
Una vez que guarde este webhook, publicar y anular la publicación de entradas y activos en Contentful activará al editor en la configuración de AWS y ¡ya está todo listo!
