baker example page template
1.0.0
베이커 빌드 도구를 사용하여 페이지를 빌드하고 게시하는 방법을 보여줍니다.
Los Angeles Times는 Baker를 사용하여 latimes.com/projects에 게시된 정적 페이지를 생성합니다. Times 시스템은 이와 유사한 저장소의 개인 버전에 의존합니다. 이 단순화된 예는 Amazon S3의 퍼블릭 버킷에 스테이징 및 프로덕션 버전을 게시합니다.
로컬 테스트 서버 실시간 업데이트
Nunjucks를 사용한 HTML 템플릿
Sass를 사용한 확장 CSS
Rollup 및 Babel을 사용한 JavaScript 번들링
quaff를 사용한 데이터 가져오기
구조화된 입력을 기반으로 한 동적 페이지 생성
GitHub Action을 통해 각 push 이벤트의 스테이징 환경에 각 분기를 자동 배포합니다.
GitHub Action을 통해 각 release 이벤트에서 프로덕션 환경에 푸시 버튼 배포
datadesk/notify-slack-on-build를 통해 각 배포 상태를 전달하는 Slack 메시지 Github Action
Node.js 버전 12, 14 또는 16(최소 12.20, 14.14 또는 16.0).
노드 패키지 관리자
자식
약간의 구성을 통해 이 템플릿을 사용하여 페이지를 쉽게 게시할 수 있습니다. 약간의 사용자 정의를 통해 원하는 대로 보이게 만들 수 있습니다. 이 가이드에서는 기본 사항을 소개합니다.
새 페이지 만들기
저장소 탐색
자산에 접근하기
데이터에 접근하기
동적 페이지
전개
전역 변수
Baker.config.js
첫 번째 단계는 GitHub의 "이 템플릿 사용" 버튼을 클릭하여 저장소의 복사본을 만드는 것입니다.
프로젝트에 대한 슬러그를 제공하라는 메시지가 표시됩니다. 완료되면 https://github.com/your-username/your-slug 에서 새 저장소를 사용할 수 있습니다.
다음으로 코드 작업을 위해 컴퓨터에 복제해야 합니다.
터미널을 열고 코드 폴더로 이동하세요. 프로젝트를 폴더에 복제합니다. 그러면 프로젝트가 컴퓨터에 복사됩니다.
자식 클론 https://github.com/your-username/your-slug
해당 명령이 작동하지 않으면 컴퓨터가 다르게 설정되어 SSH를 사용하여 저장소에 복제해야 하기 때문일 수 있습니다. 터미널에서 이것을 실행해 보세요:
git clone [email protected]:사용자 이름/your-slug.git
저장소 다운로드가 완료되면 your-slug로 이동하여 Node.js 종속성을 설치하세요.
npm 설치
종속성이 설치되면 프로젝트를 미리 볼 수 있습니다. 다음을 실행하여 테스트 서버를 시작합니다.
npm 시작
이제 브라우저에서 localhost:3000 으로 이동하세요. 사용자 정의를 위한 상용구 페이지가 표시되어야 합니다.
또 다른 방법은 Reuters 그래픽 부서에서 개발한 명령줄 스캐폴딩 도구인 bluprint를 사용하여 새 페이지를 만드는 것입니다.
청사진 추가 https://github.com/datadesk/baker-example-page-template mkdir 내-새-페이지cd 내-새-페이지 청사진 시작 베이커-예제-페이지
페이지 템플릿에서 새 프로젝트를 복제할 때 찾을 수 있는 표준 파일과 폴더는 다음과 같습니다. 특정 파일을 작업하는 데 다른 파일보다 더 많은 시간이 소요되지만 해당 파일이 수행하는 작업에 대한 일반적인 이해를 갖는 것이 좋습니다.
데이터 폴더에는 프로젝트와 관련된 데이터가 포함되어 있습니다. 우리는 이 폴더를 사용하여 프로젝트가 어떤 URL에 있어야 하는지와 같은 모든 프로젝트에 대한 필수 정보를 저장합니다. .aml , .csv 및 .json 포함하여 다양한 다른 데이터 유형을 여기에 저장할 수도 있습니다.
meta.aml 파일에는 헤드라인, 작성자, 슬러그, 게시 날짜 및 기타 필드와 같은 페이지에 대한 중요한 정보가 포함되어 있습니다. 이를 작성하면 페이지가 올바르게 표시되고 검색 엔진에서 색인을 생성할 수 있습니다. 모든 속성의 전체 목록은 참조 자료에서 찾을 수 있습니다. 원하는 만큼 옵션을 많이 또는 적게 포함하도록 확장할 수 있습니다.
사이트의 기본 템플릿과 재사용 가능한 코드 조각을 저장하는 폴더입니다. 시작할 때 여기서 아무것도 변경할 가능성이 없습니다. 고급 사용 사례에서는 여러 페이지에서 재사용되는 코드를 저장할 수 있는 곳입니다.
base.htmlbase.html 파일에는 우리가 만드는 모든 페이지에 있는 모든 기본 HTML이 포함되어 있습니다. 여기의 예는 설계상 초보적인 것입니다. 실제 구현에는 더 많은 것을 포함하고 싶을 것입니다.
작업공간은 웹에 게시할 필요가 없는 프로젝트와 관련된 모든 것을 넣을 수 있는 장소입니다. AI 파일, 코드 조각, 글쓰기 등은 귀하에게 달려 있습니다.
이는 이미지, 비디오, 오디오, 글꼴 등과 같은 미디어 및 기타 자산을 저장하는 데 사용됩니다. static 템플릿 태그를 통해 페이지로 가져올 수 있습니다.
JavaScript 파일은 이 폴더에 저장됩니다. JavaScript의 기본 파일은 app.js 라고 하며, 여기에 코드를 직접 작성할 수 있습니다. npm 을 통해 설치된 패키지는 다른 Node.js 스크립트처럼 가져오고 실행할 수 있습니다. 이 폴더에 JavaScript 코드를 작성하기 위해 다른 파일을 생성할 수 있지만 파일이 app.js 에서 부팅되는지 확인해야 합니다.
우리의 스타일시트는 개발자가 CSS를 더 잘 제어할 수 있는 강력한 스타일시트 언어인 SASS로 작성되었습니다. SASS가 익숙하지 않다면 스타일시트에 일반 CSS를 작성할 수 있습니다.
스타일 폴더는 프로젝트에 모든 사용자 정의 스타일을 추가할 수 있는 스타일시트( app.scss )로 구성되어 있지만 때로는 추가 스타일시트를 만들어 app.scss 로 가져오고 싶을 수도 있습니다. 이 예제 프로젝트에는 간단한 사이트를 시뮬레이션하는 데 필요한 최소한의 항목만 포함되어 있습니다. 실제 구현에서는 훨씬 더 많은 것부터 시작하고 싶을 것입니다.
baker.config.js 파일은 Baker가 프로젝트를 제공하고 빌드하는 데 사용하는 옵션을 넣는 곳입니다. 이 파일의 다른 곳에 완전히 문서화되어 있습니다. domain 설정을 제외하고 고급 사용자만 이 파일을 변경해야 합니다.
페이지의 기본 템플릿입니다. 여기가 페이지를 레이아웃하는 곳입니다. Nujucks 템플릿 시스템을 사용하여 HTML을 생성합니다.
이 파일은 프로젝트에 사용되는 노드 종속성을 추적합니다. npm install 실행하면 추가한 라이브러리가 여기에서 자동으로 추적됩니다.
이는 GitHub가 프로젝트 및 코드와 상호 작용하는 데 사용하는 파일을 저장하기 위한 특수 디렉터리입니다. .github/workflows 디렉터리에는 개발 배포를 처리하는 GitHub Action이 포함되어 있습니다. 여기서는 아무것도 편집할 필요가 없습니다.
자산 디렉터리의 파일 저장소는 배포 프로세스의 일부로 최적화되고 해시됩니다. 이미지 및 기타 정적 파일에 대한 참조를 보장하려면 {% static %} 태그를 사용해야 합니다. 이렇게 하면 파일이 게시될 때 파일이 많이 캐시되고 이미지에 대한 링크가 모든 환경에서 작동합니다. 모든 사진과 비디오에 이 기능을 사용하고 싶을 것입니다.
<그림>
<img src="{% static 'assets/images/baker.jpg' %}" alt="베이커 로고" width=200>
</Figure> _data 폴더에 저장된 구조화된 데이터 파일은 템플릿 태그 또는 JavaScript를 통해 액세스할 수 있습니다. 이 데모에서는 가능한 내용을 설명하기 위해 example.json 이라는 파일이 포함되었습니다. CSV, YAML 및 AML과 같은 다른 파일 형식이 지원됩니다.
_data 폴더의 파일은 템플릿 내에서 해당 이름으로 사용할 수 있습니다. 따라서 _data/example.json 사용하면 다음과 같이 작성할 수 있습니다.
{예제 %}의 obj에 대한 %
{{ obj.연도 }}: {{ obj.wheat }}{% endfor %}Baker에서 프로젝트를 구축하는 모든 사람의 일반적인 요구 사항은 JavaScript 파일 내의 원시 데이터에 액세스하는 것입니다. 종종 이 데이터는 d3 또는 Svelte를 사용하여 작성된 코드에 전달되어 그래픽을 그리거나 페이지에 HTML 테이블을 생성합니다.
액세스 중인 데이터가 이미 라이브 상태로 유지될 것으로 신뢰하는 URL에서 사용할 수 있는 경우 이는 쉽습니다. 하지만 그렇지 않고, 본인이 직접 준비한 데이터라면 어떨까요?
_data 폴더의 기록에 접근할 수 있습니다. 유일한 주의사항은 이 파일을 사용 가능한 상태로 변환하는 작업은 귀하의 책임이라는 것입니다. 이에 대한 좋은 라이브러리는 d3-fetch 입니다.
Baker가 이해하는 방식으로 이 파일에 대한 URL을 작성하려면 다음 형식을 사용하십시오.
import { json } from 'd3-fetch';// 첫 번째 매개변수는 파일 경로여야 합니다.// 두 번째 매개변수는 *반드시* "import.meta.url"이어야 합니다.const url = new URL('../_data /example.json', import.meta.url);// 호출 inconst data = wait json(url); 또 다른 접근 방식은 데이터를 템플릿에 script 태그로 인쇄하는 것입니다. jsonScript 필터는 전달된 변수를 가져와 JSON.stringify 실행하고 매개변수로 전달한 ID가 설정된 <script> 태그 내의 HTML로 JSON을 출력합니다.
{{ 예제|jsonScript('example-data') }}해당 작업이 완료되면 이제 JavaScript의 ID로 페이지에 저장된 JSON을 검색할 수 있습니다.
// inconst dataElement = document.getElementById('example-data')에서 전달한 동일한 ID를 사용하여 생성된 jsonScript 요소를 가져옵니다.// 해당 요소의 콘텐츠를 JSON으로 변환// "data"로 수행해야 하는 작업을 수행합니다. !const 데이터 = JSON.parse(dataElement.textContent); URL 방법이 권장되지만 추가 네트워크 요청을 피하려는 경우에는 이 방법이 여전히 선호될 수 있습니다. 또한 .csv 데이터를 JSON으로 변환하는 데 특수 라이브러리가 필요하지 않다는 추가 이점도 있습니다.
baker.config.js 파일의 createPages 옵션에 구조화된 데이터 소스를 제공하여 정적 페이지를 무제한으로 생성할 수 있습니다. 예를 들어, 이 코드 조각은 example.json 파일의 모든 레코드에 대한 페이지를 생성합니다.
기본값 내보내기 {
// ... 이 옵션 위의 다른 모든 옵션은 요점을 설명하기 위해 제외되었습니다.
createPages: createPages(createPage, data) {// _data 폴더에서 데이터 가져오기const pageList = data.example;// recordsfor(const d of pageList) { // 각 객체에 사용될 기본 템플릿 설정 . _layouts 폴더에 있습니다. const template = 'year-detail.html'; // 페이지의 URL을 설정합니다. const url = `${d.year}`; // 템플릿의 컨텍스트에 전달될 변수를 설정합니다. const context = { obj: d }; // 제공된 함수를 사용하여 페이지를 렌더링합니다. createPage(template, url, context);}
},}; 단일 템플릿으로 /baker-example-page-template/1775/ 및 /baker-example-page-template/1780/] 과 같은 URL을 만드는 데 사용할 수 있습니다.
이 리포지토리에서 생성된 페이지를 배포하려면 먼저 Amazon AWS 계정을 구성하고 GitHub 계정에 자격 증명 세트를 추가해야 합니다.
먼저 Amazon의 S3 스토리지 서비스에 버킷 2개를 생성해야 합니다. 하나는 준비 사이트용입니다. 다른 하나는 생산 현장용입니다. 이 간단한 예에서는 각각 공개 액세스를 허용하고 정적 웹 사이트를 제공하도록 구성되어야 합니다. Los Angeles Times에서 운영하는 것과 같은 보다 정교한 구성에서는 버킷을 등록된 도메인 이름과 연결하고 인증 체계를 통해 대중이 볼 수 없도록 보호된 준비 사이트를 만들 수 있습니다.
그런 다음 해당 버킷의 이름은 사이트를 배포하는 작업에 액세스할 수 있는 GitHub "비밀"로 저장되어야 합니다. 귀하의 계정이나 조직에 대한 설정 패널을 방문해야 합니다. 먼저 이 두 가지 비밀을 추가하세요.
| 이름 | 값 |
|---|---|
BAKER_AWS_S3_STAGING_BUCKET | 스테이징 버킷의 이름 |
BAKER_AWS_S3_STAGING_REGION | 스테이징 버킷이 생성된 S3 리전 |
BAKER_AWS_S3_PRODUCTION_BUCKET | 프로덕션 버킷의 이름 |
BAKER_AWS_S3_PRODUCTION_REGION | 프로덕션 버킷이 생성된 S3 리전 |
다음으로 두 버킷에 공개 파일을 업로드할 수 있는 AWS의 키 페어가 있는지 확인해야 합니다. 값은 비밀에도 추가되어야 합니다.
| 이름 | 값 |
|---|---|
BAKER_AWS_ACCESS_KEY_ID | AWS 액세스 키 |
BAKER_AWS_SECRET_ACCESS_KEY | AWS 비밀 키 |
이 리포지토리에 포함된 GitHub Action은 모든 브랜치에 대한 스테이징 버전을 자동으로 게시합니다. 예를 들어 기본 main 브랜치에 푸시된 코드는 https://your-staging-bucket-url/your-repo/main/ 에 표시됩니다.
bugfix 라는 새 git 브랜치를 생성하고 코드를 푸시하면 곧 https://your-staging-bucket-url/your-repo/bugfix/ 에서 새로운 스테이징 버전을 볼 수 있습니다.
페이지를 라이브로 보내기 전에 URL에 대한 최종 슬러그를 결정해야 합니다. 페이지가 게시될 버킷의 하위 디렉터리가 설정됩니다. 이 기능을 사용하면 The Times는 각 페이지가 다른 저장소에서 관리되는 동일한 버킷 내에 수많은 페이지를 게시할 수 있습니다.
1단계는 URL의 슬러그를 _data/meta.aml 구성 파일에 입력하는 것입니다.
슬러그: 귀하의 페이지 슬러그
슬러그가 이미 제거되지 않았는지 확인하는 것은 결코 나쁜 생각이 아닙니다. https://your-production-bucket-url/your-slug/ 방문하여 페이지를 찾을 수 없음 오류가 반환되는지 확인하면 됩니다.
버킷의 루트에 페이지를 게시하려면 슬러그를 null로 남겨두면 됩니다.
강타:
다음으로 구성 파일에 대한 변경 사항을 커밋하고 GitHub의 기본 분기에 푸시되었는지 확인합니다.
자식 추가 _data/meta.aml git commit -m "페이지 슬러그 설정" git push 원본 메인
GitHub 저장소 페이지의 릴리스 섹션을 방문하세요. 레포 홈페이지에서 확인하실 수 있습니다.
새 릴리스 초안을 작성합니다.
여기에서 새 태그 번호를 생성합니다. 좋은 접근 방식은 의미론적 버전 관리 표준을 따르는 xxx 형식 번호로 시작하는 것입니다. 1.0.0은 좋은 시작입니다.
마지막으로 하단의 큰 녹색 버튼을 누르고 릴리스를 보냅니다.
몇 분 정도 기다리면 페이지가 https://your-production-bucket-url/your-slug/ 에 표시됩니다.
베이커 테스트 서버는 다음 옵션으로 시작하여 더 자세한 로그를 기록할 수 있습니다.
디버그=1 npm 시작
베이커 실행으로 로그를 제한하려면 다음 안내를 따르세요.
디버그=베이커:* npm 시작
빌드에 실패하면 터미널을 통해 로컬로 정적 사이트를 직접 만들어 볼 수 있습니다. 페이지 작성에 오류가 있으면 터미널에 인쇄됩니다.
npm 실행 빌드
Baker는 생성하는 모든 페이지에서 동일한 전역 변수 세트와 생성 중인 현재 페이지를 기반으로 설정되는 또 다른 페이지별 변수 세트를 제공합니다. 이러한 변수를 사용하여 조건부로 페이지에 콘텐츠를 추가하거나 현재 페이지를 기반으로 관련 없는 데이터를 필터링할 수 있습니다.
NODE_ENV NODE_ENV 변수는 항상 development 또는 production 두 값 중 하나입니다. 이는 페이지에서 실행 중인 빌드 유형에 해당합니다.
npm start 실행하면 development 모드에 있는 것입니다. npm run build 실행하면 production 모드에 있는 것입니다.
이는 development 모드에 있을 때만 페이지에 항목을 추가하는 데 가장 유용합니다.
{% if NODE_ENV == 'development' %}<p>실시간 사이트에서는 이 내용을 절대 볼 수 없습니다!</p>{% endif %}DOMAIN DOMAIN 변수는 항상 baker.config.js 에 전달된 domain 옵션과 동일하거나 전달되지 않은 경우 빈 문자열입니다.
PATH_PREFIX PATH_PREFIX 변수는 항상 baker.config.js 에 전달된 pathPrefix 옵션과 동일하거나 전달되지 않은 경우 단일 슬래시( / )입니다.
page.url 현재 페이지에 대한 프로젝트 상대 URL입니다. baker.config.js 파일에 pathPrefix 제공된 경우 이를 포함합니다. 즉, 수행 중인 모든 프로젝트 경로를 설명하고 프로젝트의 올바른 페이지를 가리킵니다.
page.absoluteUrl 현재 페이지의 절대 URL입니다. 이는 domain , pathPrefix 및 현재 경로를 전체 URL로 결합합니다. 이는 현재 소셜 <meta> 태그에 대한 표준 URL과 모든 URL을 출력하는 데 사용됩니다.
<link rel="canonical" href="{{ page.absoluteUrl }}">page.inputUrl 이는 현재 프로젝트 디렉터리를 기준으로 이 페이지를 만드는 데 사용된 원본 템플릿의 경로입니다. page-two/index.html 에 HTML 파일이 있는 경우 page.inputUrl page-two/index.html 입니다.
page.outputUrl _dist 폴더를 기준으로 이 페이지를 생성하기 위해 출력된 HTML 파일의 경로입니다. page-two.html 에 HTML 파일이 있는 경우 page.outputUrl page-two/index.html 입니다.
우리가 작업하는 모든 Baker 프로젝트에는 루트 디렉터리에 baker.config.js 파일이 포함되어 있습니다. 이 파일은 프로젝트를 올바르게 빌드할 수 있도록 Baker에 정보를 전달하는 역할을 합니다.
기본값 내보내기 {
// 자산이 있는 디렉토리
자산: '자산',
// 페이지 생성
createPages: 정의되지 않음,
// 데이터 디렉토리
데이터: '_data',
// 경로 구축에 사용할 선택적 사용자 정의 도메인
도메인: 정의되지 않음,
// 각 JavaScript 진입점의 경로 또는 경로 덩어리
진입점: 'scripts/app.js',
// 전체 입력 디렉터리, 일반적으로 현재 폴더
입력: process.cwd(),
// 템플릿 레이아웃, 매크로 및 포함이 있는 위치
레이아웃: '_layouts',
// 전역 변수의 키와 값을 가진 객체
// 모든 Nunjucks 템플릿에 전달됨
nunjucks변수: 정의되지 않음,
// 사용자 정의를 추가하기 위한 키(이름) + 값(함수) 개체
// Nunjucks로 필터링
nunjucksFilters: 정의되지 않음,
// 사용자 정의를 추가하기 위한 키(이름) + 값(함수)의 객체
// Nunjucks에 태그 지정
nunjucks태그: 정의되지 않음,
// 컴파일된 파일을 출력할 위치
출력: '_dist',
// 모든 확인된 경로의 시작 부분에 추가할 접두사, 방법
// 슬러그 작동
경로 접두사: '/',
// 모든 자산을 넣을 선택적 디렉터리, 거의 사용되지 않음
staticRoot: '',}; 기본값: ”assets”
이는 Baker에게 자산 디렉토리로 처리할 폴더를 알려줍니다. 이를 변경할 필요는 없습니다.
기본값: undefined
createPages 는 프로젝트의 데이터와 템플릿을 사용하여 페이지를 동적으로 생성할 수 있게 해주는 선택적 매개변수입니다.
기본값 내보내기 {
// …
// createPage - 템플릿, 출력 이름 및 데이터 컨텍스트를 전달합니다.
// data - `_data` 폴더에 준비된 데이터
createPages(createPage, data) {for (const title of data.titles) { createPage('template.html', `${title}.html`, {context: { title }, });}
},}; 기본값: ”_data”
data 옵션은 Baker에게 데이터 소스로 처리할 폴더를 알려줍니다. 이를 변경할 필요는 없을 것입니다.
기본값: undefined
domain 옵션은 Baker가 절대 URL을 구축할 때 무엇을 사용할지 알려줍니다. bakery-template 이를 https://www.latimes.com 으로 미리 설정합니다.
기본값: ”scripts/app.js”
entrypoints 옵션은 Baker에게 스크립트 번들의 시작점으로 처리할 JavaScript 파일을 알려줍니다. 이는 파일 또는 파일 glob에 대한 경로일 수 있으므로 동시에 여러 번들을 생성할 수 있습니다.
기본값: process.cwd()
input 옵션은 Baker에게 전체 프로젝트의 기본 디렉터리로 처리할 폴더를 알려줍니다. 기본적으로 이는 baker.config.js 파일이 있는 폴더입니다. 이를 설정할 필요가 없을 것입니다.
기본값: ”_layouts”
layouts 옵션은 Baker에게 템플릿, 포함 및 매크로가 있는 위치를 알려줍니다. 기본적으로 이는 _layouts 폴더입니다. 이를 설정할 필요는 없을 것입니다.
기본값: undefined
nunjucksFilters 사용하여 사용자 정의 필터를 전달할 수 있습니다. 객체에서 각 키는 필터의 이름이고, 함수 값은 필터를 사용할 때 호출되는 값입니다.
기본값 내보내기 {
// ...
// Nunjucks에 추가할 필터 객체를 전달합니다.
nunjucksFilters: {square(n) { n = +n; n * n을 반환;}
},} {{ 값|제곱 }} 기본값: undefined
nunjucksTags 사용하여 사용자 정의 태그를 전달할 수 있습니다. 이는 텍스트 또는 HTML 블록을 더 쉽게 출력할 수 있다는 점에서 필터와 다릅니다.
기본값 내보내기 {
// ...
// Nunjucks에 추가할 필터 객체를 전달합니다.
nunjucksTags: {doubler(n) { return `<p>${n} 두 배는 ${n * 2}</p>`;}
},}; {% 더블러 값 %} 기본값: ”_dist”
output 옵션은 npm run build 실행될 때 Baker에게 파일을 저장할 위치를 알려줍니다. 기본적으로 이는 _dist 폴더입니다. 이를 설정할 필요는 없을 것입니다.
기본: ”/”
pathPrefix Baker에게 자신이 구축하는 모든 URL에 추가할 경로 접두어를 알려줍니다. domain 도 전달되면 절대 URL을 작성할 때 pathPrefix 와 결합됩니다. 일반적으로 이를 수동으로 설정하지 않습니다. 프로젝트 슬러그를 사용하여 URL을 구축하기 위해 배포하는 동안 사용됩니다.
기본: ””
staticRoot 옵션은 Baker에게 모든 자산을 추가 디렉터리에 넣도록 지시합니다. 이는 중첩 없이 모든 단일 페이지에 고유한 슬러그가 있어야 하는 프로젝트에 유용하며 모든 정적 자산을 공유할 수 있습니다. 그러나 이는 특별한 경우이며 배포를 위한 사용자 정의 설정이 필요합니다. 정당한 이유 없이 이것을 사용하려고 시도하지 마십시오.
