stacy
v2.0.0
Stacy는 Contentful CMS의 콘텐츠를 Handlebars 템플릿과 결합하여 웹사이트 페이지를 생성하는 웹사이트 생성기입니다.
Stacy는 Contentful의 항목 콘텐츠 유형을 웹 사이트 프로젝트의 핸들바 템플릿과 일대일 관계로 일치시킵니다. 콘텐츠 모델 에 정의된 모든 항목 유형에 대한 템플릿이 있습니다. Stacy의 관점에서는 페이지 항목 과 모듈 항목 이라는 두 가지 유형의 항목이 있습니다. 템플릿과 결합된 페이지 항목은 고유한 URL에 단일 웹사이트 페이지를 생성합니다. 모듈 항목은 재사용 가능한 콘텐츠 조각을 생성하거나 단순히 콘텐츠를 더 작은 조각으로 나누어 콘텐츠와 템플릿 구조를 제공하기 위해 Contentful의 참조 필드를 사용하여 페이지 및 기타 모듈에 포함될 수 있습니다.
Stacy가 기존의 많은 정적 웹 사이트 생성기와 다른 점은 웹 사이트를 인터넷에서 제공할 수 있는 Amazon Cloud의 S3 버킷에 자동 게시하는 기능을 지원한다는 것입니다. Stacy는 Webhooks 기능을 통해 Contentful에 연결할 수 있는 특수 인프라를 Amazon Cloud에 배포합니다. Contentful 공간에서 콘텐츠가 업데이트되면 Stacy가 Amazon Cloud에 배포한 웹 사이트 인프라에 알림이 전송되고 업데이트의 영향을 받는 웹 사이트 페이지만 자동으로 재생성되어 다시 게시됩니다. 수동 웹 사이트 재생성 및 재배포가 필요하지 않습니다.
Stacy를 사용할 때 귀하의 웹 사이트는 일반적으로 버전 제어를 위해 git 저장소에서 확인되는 NPM 프로젝트입니다. 프로젝트에는 핸들바 템플릿과 정적 콘텐츠(예: CSS 스타일시트, 웹 사이트 디자인에 사용되는 이미지, 글꼴 등)가 포함되어 있으며, 웹 사이트 콘텐츠는 Contentful 공간에 있습니다. 웹 사이트 프로젝트에서 웹 사이트 개발자는 Stacy 명령줄 도구를 사용하여 사이트를 개발, 게시 및 다시 게시합니다. 웹 사이트가 Amazon Cloud에 게시되면 콘텐츠 작성자는 Contentful UI로만 작업합니다.
자세한 튜토리얼/연습은 Stacy로 웹 사이트 만들기를 참조하세요.
먼저, 웹 사이트 콘텐츠를 위한 콘텐츠 공간이 필요합니다. 그런 다음 웹 사이트에 대한 새 프로젝트를 만들 수 있습니다.
npm과 함께 Node.js 버전 10.16.3 이상이 설치되어 있는지 확인하세요. Amazon Cloud에 웹 사이트를 게시하려면 AWS CLI도 설치해야 합니다.
Stacy를 전역적으로 설치하는 것부터 시작하세요.
npm install -g stacy
콘텐츠가 있는 공간에서 공간 설정→API 키로 이동하여 콘텐츠 전달/미리 보기 토큰 에 API 키를 추가하세요. Stacy 환경을 Contentful 공간에 연결하는 데 사용할 공간 ID 및 Content Delivery API 액세스 토큰 값을 참고하세요.
이제 웹사이트에 대한 초기 프로젝트를 생성할 수 있습니다.
stacy new --cf-space <your space ID> --cf-access-token <your access token> mywebsite
그러면 현재 디렉터리에 "mywebsite"라는 새 프로젝트 디렉터리가 생성됩니다. "mywebsite" 값을 사이트 ID 라고 합니다. 웹사이트를 식별하는 다른 값을 사용하세요. 값은 URL에 적합해야 합니다(소문자, 숫자 및 대시).
프로젝트 디렉토리에서 정적 콘텐츠를 /static 아래에 두고(이것은 웹사이트에 있는 그대로 복사됩니다) 항목 템플릿을 /templates 아래에 놓습니다. 템플릿 파일의 이름(확장자 제외)은 콘텐츠가 포함된 콘텐츠 모델 의 해당 항목 콘텐츠 유형과 정확히 일치해야 합니다. /templates 아래에서 템플릿 파일을 하위 폴더로 구성할 수 있습니다. 그러나 파일 이름은 템플릿을 항목 콘텐츠 유형과 고유하게 일치시키는 데 사용되므로 모든 하위 폴더에서 고유해야 합니다( /templates 의 하위 폴더는 아무런 역할도 하지 않음).
참고: 일반적으로 항목의 콘텐츠와 결합된 템플릿은 HTML을 생성합니다. 다른 유형의 콘텐츠를 생성해야 하는 경우 템플릿 이름에 확장자를 추가할 수 있습니다. 예를 들어, page.hbs HTML을 생성합니다. 일반 텍스트를 생성하려면 page.txt.hbs 사용하세요. 이는 또한 page.hbs 와 page.html.hbs 동일하다는 것을 의미합니다.
이제 개발 목적으로 웹사이트를 로컬에서 실행할 수 있습니다.
stacy serve
http://localhost:8080/ 에서 귀하의 웹사이트를 볼 수 있습니다. 템플릿, 정적 콘텐츠 또는 Contentful의 콘텐츠를 편집한 후 페이지를 다시 로드하기만 하면 됩니다.
Stacy 로컬 웹 서버를 중지하려면 Ctrl+C 사용하세요.
사용 가능한 다른 명령을 보려면 stacy --help 실행하세요.
프로젝트 디렉터리의 콘텐츠는 GitHub 또는 Bitbucket과 같은 git 저장소에 체크인할 수 있습니다.
템플릿 내에서 모든 입력 필드는 콘텐츠 모델 에 정의된 필드 ID 로 사용할 수 있습니다. 템플릿에서 직접 참조할 수 있습니다. 예를 들어:
그러면 항목의 caption 필드 값이 출력됩니다. 여기에서 사용되는 것은 Name 필드가 아니라 Field ID 입니다.
Stacy는 템플릿에서 사용할 수 있는 몇 가지 특별한 도우미를 추가합니다.
module <reference field> - 참조 유형 필드에서 참조하는 모듈 항목을 포함합니다. 예를 들어, ID paragraphs 이 있는 필드가 있고 참조 목록인 경우:
asset <asset field> - 이미지와 같은 참조 자산을 포함합니다. 예를 들어:
현재 HTML <img> 태그가 렌더링되는 이미지 자산만 지원됩니다.
assetSrc <asset field> - 자산의 URL을 가져옵니다. 예를 들어:
assetTitle <asset field> - 자산의 제목을 가져옵니다. 예를 들어:
markdown <long text field> - Markdown 긴 텍스트 필드를 렌더링합니다. 예를 들어:
도우미가 이스케이프할 필요가 없는 HTML을 생성하기 때문에 여기에 필요한 삼중 중괄호에 유의하세요.
richText <rich text field> - 서식 있는 텍스트 필드를 렌더링합니다. 예를 들어:
markdown 과 마찬가지로 삼중 중괄호에 유의하세요.
json <field> - 필드의 내부 콘텐츠가 포함된 JSON 표현을 출력합니다. 예를 들어:
이 도우미는 문제를 진단하는 데 유용할 수 있습니다.
위에서 언급한 것처럼 Contentful 공간의 콘텐츠 모델 과 템플릿에서 정의한 콘텐츠 유형 간에는 일대일 관계가 있습니다.
참고: 엄밀히 말하면, 동일한 콘텐츠 항목에 대해 다양한 유형의 파일을 생성할 수 있도록 특정 콘텐츠 유형에 대해 두 개 이상의 템플릿을 가질 수 있습니다. 예를 들어 콘텐츠 유형 ID module 의 경우 module.html.hbs 및 module.xml.hbs 템플릿이 있을 수 있습니다. 첫 번째 템플릿은 항목에 대한 HTML 파일을 생성하고 두 번째 템플릿은 XML 파일을 생성합니다.
콘텐츠 유형을 정의할 때 Api 식별자 ( 콘텐츠 유형 ID 라고도 함)를 기록해 두세요. 콘텐츠 유형의 템플릿 파일은 동일한 이름(확장자 포함)을 가져야 합니다.
페이지 항목(모듈 항목과 반대)의 콘텐츠 유형에 대한 한 가지 요구 사항이 있습니다. 페이지 콘텐츠 유형은 필수 슬러그 필드를 정의해야 합니다. 필드의 값은 콘텐츠 항목이 해당 템플릿과 결합될 때 생성되는 파일의 이름을 결정합니다. 예를 들어 페이지 항목의 슬러그 값이 "index"인 경우 생성되는 페이지는 "/index.html"이 됩니다. 슬러그가 "more/terms"인 경우 페이지는 "/more/terms.html"이 됩니다. 등.
기본적으로 slug 필드의 필드 ID는 slug 여야 합니다. ID는 프로젝트의 stacy.json 파일에서 재정의될 수 있습니다. 콘텐츠 유형 정의에 필요한 슬러그 필드를 만드는 것 외에도 사용자 정의 일치 패턴 유효성 검사기를 연결하여 필드 값의 특정 형식을 확인하는 것이 좋습니다. 유효성 검사기의 정규식은 ^w[w-]*(/w[w-]*)*$ 일 수 있습니다.
AWS에 웹사이트를 배포할 준비가 되면 먼저 AWS 계정에 Stacy 인프라를 설정해야 합니다. 이를 수행하려면 먼저 여러 단계를 수행해야 합니다.
대상 S3 버킷을 생성합니다. 이곳은 귀하의 웹 사이트가 게시되고 제공되는 곳입니다(아마 CloudFront를 통해). 또는 이미 가지고 있는 버킷을 사용할 수 있습니다(Stacy는 대상 버킷의 하위 폴더에 게시하는 것도 지원합니다).
아직 없다면 Stacy가 게시자 Lambda 함수 패키지를 업로드하는 데 사용할 S3 버킷을 생성하십시오. 게시자 Lambda 함수는 Contentful 게시 및 게시 취소 이벤트에 응답하고 대상 S3 버킷의 관련 페이지와 자산을 업데이트하는 부분입니다.
게시자 패키지를 빌드합니다.
stacy build-publisher
그러면 /build/stacy-mywebsite-publisher.zip 아래 프로젝트에 게시자 Lambda 함수 패키지가 생성됩니다. 이 파일을 Lambda 함수 S3 버킷에 업로드하세요.
Stacy의 stacy new 명령은 AWS 환경을 위한 CloudFormation 템플릿을 생성하여 프로젝트의 /misc/cfn-template.json 아래에 저장했습니다. 필요한 경우 이를 검토하고 맞춤설정할 수 있습니다. 그렇지 않은 경우 AWS 계정에서 웹 사이트용 Stacy 스택을 생성하십시오.
CloudFormation 스택이 생성되면 Stacy 게시자가 생성된 웹 사이트 콘텐츠를 여기에 게시할 수 있도록 대상 S3 버킷의 정책을 조정해야 합니다. 버킷의 정책에는 다음과 같은 내용이 포함될 수 있습니다.
{
"Version" : " 2012-10-17 " ,
"Statement" : [
{
"Effect" : " Allow " ,
"Principal" : {
"AWS" : " <Stacy publisher role ARN> "
},
"Action" : [
" s3:PutObject " ,
" s3:DeleteObject "
],
"Resource" : " arn:aws:s3:::<bucket name>/* "
}
]
} 위 정책에서 Stacy 게시자 역할 ARN을 CloudFormation 스택의 PublisherRoleArn 출력 매개변수에서 찾을 수 있는 값으로 바꾸고, 버킷 이름을 대상 웹 사이트 버킷 이름(정책이 적용되는 버킷)으로 바꿉니다.
이제 게시를 위한 개발 환경을 준비해야 합니다. 웹사이트 프로젝트에서 .env 파일을 열고 편집하세요. 여기에서 모든 AWS_* 변수를 올바른 값으로 설정합니다. CloudFormation 스택의 PublishEventSourceMappingId 출력 매개변수에서 AWS_PUBLISH_EVENT_SOURCE_MAPPING 변수의 값을 찾을 수 있습니다.
.env 파일이 올바르게 설정되면 다음을 사용하여 웹사이트를 게시할 수 있습니다.
stacy publish
마지막 설정 단계 중 하나는 게시 및 게시 취소 이벤트에서 Stacy 게시자를 호출하도록 Contentful 공간에서 웹후크를 구성하는 것입니다. AWS 계정의 API Gateway 서비스에서 Stacy가 생성한 API를 찾으세요. API의 prod 단계에는 POST /publish 메소드가 하나만 있습니다. 호출 URL을 기록해 두십시오.
또한 API 키 섹션으로 이동하여 Stacy용으로 생성된 API 키 값을 확인하세요.
콘텐츠가 있는 공간에서 공간 설정→웹훅 으로 이동하여 웹훅을 추가하세요. URL 필드에 API Gatwey의 호출 URL을 입력합니다( POST 메서드는 그대로 둡니다). 그런 다음 트리거 섹션에서 특정 트리거 이벤트 선택 옵션을 선택합니다. 항목 및 자산 행에서 게시 및 게시 취소 확인란을 선택합니다(4개의 확인란이 모두 선택됨).
헤더 섹션에서 비밀 헤더 추가를 클릭합니다. 키 필드에 "X-API-Key"를 입력하고 값 필드에 API 게이트웨이의 API 키를 입력합니다.
이 웹훅을 저장하면 Contentful에서 항목과 자산을 게시 및 게시 취소하면 AWS 설정에서 게시자가 트리거되고 모든 준비가 완료됩니다!
