copenhagen_theme
v4.2.3
Copenhagen 테마는 기본 Zendesk Guide 테마입니다. 반응성과 접근성이 뛰어나도록 설계되었습니다. 여기에서 Zendesk Guide 사용자 지정에 대해 자세히 알아보세요.
도움말 센터의 코펜하겐 테마는 다음으로 구성됩니다.
Guide에서 사용할 수 있는 Copenhagen 테마의 최신 버전입니다. 이 저장소를 시작점으로 사용하여 자신만의 사용자 정의 테마를 구축할 수 있습니다. 적절하다고 판단되면 이 저장소를 포크할 수 있습니다. 즐겨 사용하는 IDE를 사용하여 ZCLI를 사용하여 웹 브라우저에서 로컬로 테마를 개발하고 변경 사항을 미리 볼 수 있습니다. 자세한 내용은 zcli 테마 문서를 읽어보세요.
이 저장소를 포크한 후에는 자유롭게 템플릿, CSS, JavaScript를 편집하고 자산을 관리할 수 있습니다.
매니페스트를 사용하면 테마 설정 그룹을 정의한 후 테마 센터의 UI를 통해 변경할 수 있습니다. 여기에서 매니페스트 파일에 대한 자세한 내용을 읽을 수 있습니다.
file 유형의 변수가 있는 경우 /settings 폴더에 해당 변수에 대한 기본 파일을 제공해야 합니다. 이 파일은 기본적으로 설정 패널에서 사용되며 사용자는 원하는 경우 다른 파일을 업로드할 수 있습니다. 전. 섹션의 배경 이미지에 대한 변수를 갖고 싶다면 매니페스트 파일의 변수는 다음과 같습니다.
{
...
"settings" : [ {
"label" : "Images" ,
"variables" : [ {
"identifier" : "background_image" ,
"type" : "file" ,
"description" : "Background image for X section" ,
"label" : "Background image" ,
} ]
} ]
} 그러면 설정 폴더 내에서 background_image 라는 파일을 찾습니다.
자산 폴더에 자산을 추가하고 CSS, JavaScript 및 템플릿에서 사용할 수 있습니다. 여기에서 자산에 대한 자세한 내용을 읽을 수 있습니다.
테마를 사용자 정의한 후 저장소를 zip 파일로 다운로드하여 테마 센터로 가져올 수 있습니다.
여기에서 가져오기에 대한 설명서를 따를 수 있습니다.
GitHub에서 직접 가져올 수도 있습니다. 여기에서 자세히 알아보세요.
테마에는 사용 가능한 모든 기능을 갖춘 헬프 센터에 사용되는 모든 템플릿이 포함되어 있습니다. 테마의 템플릿 목록:
다음에 대해 최대 10개의 선택적 템플릿을 추가할 수 있습니다.
templates/article_pages , templates/category_pages 또는 templates/section_pages 폴더 아래에 파일을 생성하면 됩니다. 여기에서 자세히 알아보세요.
우리는 테마에 사용되는 JS 및 CSS 파일( style.css 및 script.js 을 컴파일하기 위해 Rollup을 사용합니다. 릴리스 중에 다시 생성되므로 직접 편집하지 마십시오.
시작하려면:
$ yarn install
$ yarn start 이것은 src 와 styles 의 모든 소스 코드를 컴파일하고 변경 사항을 감시합니다. 또한 preview 도 시작됩니다.
참고:
script.js 컴파일할 때 의도적으로 babel을 사용하지 않습니다. 널리 지원되는 ecmascript 기능(ES2015)만 사용해야 합니다.style.css , script.js 및 assets 폴더 내의 파일을 직접 편집하지 마십시오. 릴리스 중에 재생성됩니다.yarn zcli login -i 실행하십시오. Copenhagen 테마에는 몇 가지 JavaScript 자산이 포함되어 있지만 assets 폴더에 다른 자산을 배치하여 테마에 추가할 수 있습니다.
버전 4.0.0부터 Copenhagen 테마는 일부 React 구성 요소를 사용하여 UI의 일부를 렌더링합니다. 이러한 구성 요소는 src/modules 폴더에 있으며 Zendesk Garden 구성 요소 라이브러리를 사용하여 구축됩니다.
이러한 구성 요소는 롤업 빌드 프로세스의 일부로 기본 JavaScript 모듈로 번들로 제공되며 assets 폴더에 JS 파일로 내보내집니다. 테마가 설치되면 자산의 이름이 바뀌므로 자산 헬퍼를 사용하여 모듈을 가져와야 합니다.
모듈 가져오기 프로세스를 더 쉽게 만들기 위해 모듈 이름을 자산 URL에 매핑하는 가져오기 맵을 생성하는 롤업 플러그인을 추가했습니다. 그런 다음 이 가져오기 맵은 빌드 중에 document_head.hbs 템플릿에 주입됩니다.
예를 들어, src/modules/my-module 폴더에 my-module 이라는 모듈을 정의한 경우 다음과 같이 이를 rollup.config.mjs 파일에 추가할 수 있습니다.
export default defineConfig ( [
// ...
// Configuration for bundling modules in the src/modules directory
{
// ...
input : {
"my-module" : "src/modules/my-module/index.js" ,
} ,
// ...
}
] ) ; 롤업은 assets 폴더에 my-module-bundle.js 라는 파일을 생성하고 이 가져오기 맵이 document_head.hbs 템플릿에 추가됩니다.
< script type =" importmap " >
{
"imports" : {
"my-module" : "{{asset 'my-module-bundle.js'}}" ,
}
}
</ script >그런 다음 다음과 같이 템플릿에서 모듈을 가져올 수 있습니다.
I18n은 React-i18next 라이브러리를 사용하여 React 구성 요소에서 구현됩니다. 우리는 플랫 JSON 파일을 사용하고 . 복수형 구분 기호로 기본 _ 와 다르며 초기화 중에 구성됩니다.
또한 Zendesk에서 사용되는 내부 번역 시스템과 라이브러리를 통합할 수 있는 몇 가지 도구도 추가했습니다. 사용자 정의 테마를 구축하고 자신만의 번역을 제공하려는 경우 라이브러리 문서를 참조하여 번역 로드를 설정할 수 있습니다.
번역 문자열은 일반적으로 useTranslation 후크를 사용하여 키와 기본 영어 값을 전달하여 소스 코드에 직접 추가됩니다.
import { useTranslation } from 'react-i18next' ;
function MyComponent ( ) {
const { t } = useTranslation ( ) ;
return < div > { t ( "my-key" , "My default value" ) } < / div>
}코드에 기본 영어 값을 제공하면 문자열이 아직 번역되지 않은 경우 이를 대체 값으로 사용하고 소스 코드에서 번역 YAML 파일로 문자열을 추출할 수 있습니다.
복수형을 사용할 때 번역 시스템의 요청에 따라 zero , one 및 other 값에 대한 기본값을 제공해야 합니다. 이는 t 함수의 옵션에 기본값을 전달하여 수행할 수 있습니다.
t ( "my-key" , {
"defaultValue.zero" : "{{count}} items" ,
"defaultValue.one" : "{{count}} item" ,
"defaultValue.other" : "{{count}} items" ,
count : ...
} ) bin/extract-strings.mjs 스크립트를 사용하면 소스 코드에서 번역 문자열을 추출하고 이를 내부 번역 시스템에서 선택하는 YAML 파일에 넣을 수 있습니다. 스크립트 사용법은 스크립트 자체에 문서화되어 있습니다.
이 스크립트는 i18next-parser 도구를 래핑하고 해당 출력을 내부적으로 사용되는 YAML 형식으로 변환합니다. 표준 i18next-parser 출력을 번역 소스로 사용하거나 사용자 정의 변환기를 구현하는 등 사용자 정의 테마에서 유사한 접근 방식을 사용할 수 있습니다.
모든 모듈의 최신 번역을 다운로드하려면 bin/update-modules-translations.mjs 사용하세요. 그런 다음 모든 파일은 단일 [MODULE]-translations-bundle.js 파일의 빌드 프로세스에 의해 번들됩니다.
번역이 모듈에 처음 추가되면 번역 시스템의 모듈 폴더와 패키지 이름 간의 매핑을 스크립트의 MODULE 변수에 추가해야 합니다. 예를 들어, 모듈이 src/modules/my-module 에 있고 패키지 이름이 cph-theme-my-module 인 경우 다음을 추가해야 합니다.
const MODULES = {
... ,
"my-module" : "cph-theme-my-module"
}자동화된 접근성 테스트를 위해 Lighthouse를 실행하는 사용자 정의 노드 스크립트를 사용합니다.
스크립트를 실행하는 방법에는 두 가지가 있습니다.
zcli themes:preview 필요합니다.테스트 범위에 따라 위 테스트 외에도 일부 수동 테스트가 필요할 수 있습니다. ax DevTools, VoiceOver와 같은 화면 판독기, 대비 검사기 등과 같은 도구가 이러한 테스트를 도울 수 있습니다.
테마를 변경하는 동안 접근성 감사를 실행하려면 다음 안내를 따르세요.
$ yarn install
$ yarn start 루트 폴더에 .a11yrc.json 파일을 생성합니다(예제 참조).
zcli 프로필과 일치하는지 확인하기 위해 테마를 미리 보려면 계정/하위 도메인을 지정하세요.username 과 password 관리자의 자격 증명으로 입력하세요.urls 지정합니다. 비워 두면 스크립트가 모든 URL을 테스트합니다.별도의 콘솔에서 개발 모드의 접근성 감사를 실행합니다.
yarn test-a11y -d 그런 다음 A11y 감사는 1 단계에서 시작된 미리 보기에서 실행됩니다.
특정 계정의 라이브 테마에 대한 접근성 감사를 실행하려면 다음을 수행해야 합니다.
yarn installend_user_email , end_user_password , subdomain 및 urls 환경 변수로 설정하고 CI 모드에서 접근성 감사를 실행합니다. 즉: end_user_email=<EMAIL>
end_user_password=<PASSWORD>
subdomain=<SUBDOMAIN>
urls="
https://<SUBDOMAIN>.zendesk.com/hc/en-us/
https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests/new
https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests"
yarn test-a11y 무시해야 하거나 즉시 수정할 수 없는 알려진 접근성 문제가 있는 경우 스크립트 구성 개체의 무시 목록에 새 항목을 추가할 수 있습니다. 이렇게 하면 접근성 문제가 오류 대신 경고로 전환됩니다.
항목에는 다음이 포함되어야 합니다.
path ;selector .예를 들어:
custom: {
ignore: {
tabindex: [
{
path : "*" ,
selector : "body > a.skip-navigation" ,
} ,
] ,
aria - allowed - attr : [
{
path : "/hc/:locale/profiles/:id" ,
selector : "body > div.profile-info"
}
]
} ,
} , 이 예에서는 선택기 body > a.skip-navigation 이 포함된 감사 tabindex 에 대한 오류가 모든 페이지( * )에서 경고로 보고됩니다. 선택기 body > div.profile-info 가 있는 감사 aria-allowed-attr 에 대해서도 동일한 일이 발생하지만 사용자 프로필 페이지 /hc/:locale/profiles/:id 에 대해서만 발생합니다.
꼭 필요한 경우에만 사용해야 한다는 점을 명심하세요. 테마를 변경할 때 접근성이 초점이자 우선순위가 되어야 합니다.
끌어오기 요청은 GitHub(https://github.com/zendesk/copenhagen_theme)에서 환영합니다. 끌어오기 요청을 작성할 때 @zendesk/vikings를 언급해 주세요.
우리는 프로젝트 기록의 가독성을 높이고 릴리스 프로세스를 자동화하기 위해 기존 커밋을 사용합니다. 따라서 커밋 메시지는 다음 형식을 준수해야 합니다.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
즉:
chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors
우리는 커밋할 때 메시지의 유효성을 검사하기 위해 husky 와 commitlint 사용합니다.
PR이 병합되면 Github 작업을 semantic-release 와 함께 사용하여 테마의 새 버전을 릴리스합니다. 각 병합에서 semantic-release 커밋 메시지를 분석하고 의미 체계 버전 범프를 추론합니다. 그런 다음 git 태그를 생성하고 매니페스트 버전을 업데이트하며 해당 변경 로그를 생성합니다.
아래 목록은 지원되는 커밋 유형과 릴리스 및 변경 로그에 미치는 영향을 설명합니다.
| 유형 | 설명 | 풀어 주다 | 변경 내역 |
|---|---|---|---|
| 짓다 | 빌드 시스템 또는 외부 종속성에 영향을 미치는 변경 사항 | - | - |
| 하기 싫은 일 | 소스 코드를 수정하지 않는 기타 변경 사항 | - | - |
| ci | CI 구성 파일 및 스크립트 변경 사항 | - | - |
| 문서 | 문서만 변경됨 | - | - |
| 위업 | 새로운 기능 | 미성년자 | 특징 |
| 고치다 | 버그 수정 | 반점 | 버그 수정 |
| 성능 | 성능을 향상시키는 코드 변경 | 반점 | 성능 개선 |
| 리팩터링 | 버그 수정도, 기능 추가도 아닌 코드 변경 | - | - |
| 돌아가는 것 | 이전 커밋을 되돌립니다. | 반점 | 되돌리기 |
| 스타일 | 코드의 의미에 영향을 주지 않는 변경 사항(공백, 형식 지정, 세미콜론 누락 등) | - | - |
| 시험 | 누락된 테스트 추가 또는 기존 테스트 수정 | - | - |
주요 변경 사항을 추가하는 커밋은 커밋 메시지의 본문이나 바닥글에 BREAKING CHANGE 포함해야 합니다.
즉:
feat: update theme to use theming api v2
BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2
그러면 주요 릴리스가 생성되고 변경 로그에 BREAKING CHANGES 섹션이 추가됩니다.
버그 보고서는 Zendesk의 표준 지원 채널(https://www.zendesk.com/contact/)을 통해 제출해야 합니다.
