Repository files navigation

The Copenhagen theme is the default Zendesk Guide theme. It is designed to be responsive and accessible.Learn more about customizing Zendesk Guidehere.

The Copenhagen theme for Help Center consists of:

• Manifest file
• Set of templates
• Stylesheet and JavaScript files
• Assets folder.

This is the latest version of the Copenhagen theme available for Guide. It is possible to use this repository as a starting point to build your own custom theme. You can fork this repository as you see fit.You can use your favorite IDE to develop themes and preview your changes locally in a web browser usingZCLI. For details, read thezcli themes documentation.

Once you have forked this repository you can feel free to edit templates, CSS, JavaScript and manage assets.

The manifest allows you to define a group of settings for your theme that can then be changed via the UI in Theming Center.You can read more about the manifest filehere.

If you have a variable of typefile, you need to provide a default file for that variable in the/settings folder. This file will be used on the settings panel by default and users can upload a different file if they like.Ex.If you would like to have a variable for the background image of a section, the variable in your manifest file would look something like this:

{  ..."settings":[{"label":"Images","variables":[{"identifier":"background_image","type":"file","description":"Background image for X section","label":"Background image",}]}]}

And this would look for a file inside the settings folder named:background_image

You can add assets to the asset folder and use them in your CSS, JavaScript and templates.You can read more about assetshere

After you have customized your theme you can download the repository as azip file and import it into Theming Center.

You can follow the documentation for importinghere.

You can also import directly from GitHub - learn morehere.

The theme includes all the templates that are used for a Help Center that hasall the features available.List of templates in the theme:

• Article page
• Category page
• Community post list page
• Community post page
• Community topic list page
• Community topic page
• Contributions page
• Document head
• Error page
• Footer
• Header
• Home page
• New community post page
• New request page
• Requests page
• Search results page
• Section page
• Subscriptions page
• User profile page
• Service list page (optional, service catalog specific)
• Service page (optional, service catalog specific)
• Approval request list page (optional, approvals specific)
• Approval request page (optional, approvals specific)

You can add up to 10 optional templates for:

• Article page
• Category page
• Section page

You do this by creating files under the folderstemplates/article_pages,templates/category_pages ortemplates/section_pages.Learn morehere.

We use Rollup to compile the JS and CSS files that are used in the theme -style.css andscript.js. Do not edit these directly as they'll be regenerated during release.

To get started:

$yarn install$yarn start

This will compile all the source code insrc andstyles and watch for changes. It will also startpreview.

Notes:

• We intentionally do not use babel when compilingscript.js so we can get a clean bundle output. Make sure to only use widely supported ecmascript features (ES2015).
• Do not editstyle.css,script.js and the files inside theassets folder directly. They are regenerated during release.
• Preview requires login so make sure to first runyarn zcli login -i if you haven't done that before.

The Copenhagen theme comes with a few JavaScript assets, but you can add other assets to your theme by placing them in theassets folder.

From version 4.0.0, the Copenhagen theme uses some React components to render parts of the UI. These components are located in thesrc/modules folder and are built using theZendesk Garden component library.

These components are bundled as nativeJavaScript modules as part of the Rollup build process, and they are emitted as JS files in theassets folder. Since assets are renamed when a theme is installed, the modules needs to be imported using theasset helper.

To make the process of importing the modules easier, we added a Rollup plugin that generates animport map that maps the module name to the asset URL. This import map is then injected into thedocument_head.hbs template during the build.

For example, if you defined a module namedmy-module in thesrc/modules/my-module folder, you can add it to therollup.config.mjs file like this:

exportdefaultdefineConfig([// ...// Configuration for bundling modules in the src/modules directory{// ...input:{"my-module":"src/modules/my-module/index.js",},// ...}]);

Rollup will generate a file namedmy-module-bundle.js in theassets folder and this import map will be added to thedocument_head.hbs template:

<scripttype="importmap">{"imports":{"my-module":"{{asset 'my-module-bundle.js'}}",}}</script>

You can then import the module in your templates like this:

<scripttype="module">import {something }from"my-module";// ...</script>

I18n is implemented in the React components using thereact-i18next library. We use a flat JSON file and we use. as a separator for plurals, which is different from the default_ and it is configured during initialization.

We also added some tools to be able to integrate the library with the internal translation system used at Zendesk. If you are building a custom theme and you want to provide your own translations you can refer to the library documentation to setup the loading of your translations.

Translation strings are added directly in the source code, usually using theuseTranslation hook, passing the key and the default English value:

import{useTranslation}from'react-i18next';functionMyComponent(){const{ t}=useTranslation();return<div>{t("my-key","My default value")}</div>}

Providing the default English value in the code makes it possible to use it as a fallback value when strings are not yet translated and to extract the strings from the source code to the translations YAML file.

When usingplurals, you need to provide default values for thezero,one,two,few,many andother forms, as some languages have specific forms for all of these. These forms should be provided in the translations YAML file, such asthis one. This can be done manually or by running the extract script after adding the string in the code (checkString extraction for more details).

To use the plural forms in the code, you need to provide at least a default value forone and a generic value for the other plural forms. It is also possible to pass a default value forzero, if you want it to be different from the generic value. This can be done by passing the default values in theoptions of thet function.

t("my-key","{{count}} items",{"defaultValue.zero":"No items","defaultValue.one":"{{count}} item",count: ...})

Thebin/extract-strings.mjs script can be used to extract translation strings from the source code and put them in the YAML file that is picked up by our internal translation system.

To extract the strings for all the modules, run:

yarn i18n:extract

To extract the strings for a specific module, run:

yarn i18n:extract --module=module-name

You can also pass the--mark-obsolete flag to mark removed strings as obsolete:

yarn i18n:extract --mark-obsolete

If you are adding a new module, you need first to create the initialsrc/modules/[MODULE]/translations/en-us.yml file with the header containing the title and package name:

title:"My Module"packages:  -"package-name"

The script wraps thei18next-parser tool and converts its output to the YAML format used internally. It is possible to use a similar approach in a custom theme, either using the standardi18next-parser output as the source for translations or implementing a custom transformer.

You can runyarn i18n:update-translations to download the latest translations files for all the modules. The script downloads all the locale files for each module, fetching the package name from thesrc/modules/[MODULE]/translations/en-us.yml file, and saves them in thesrc/modules/[MODULE]/translations/locales folder. As for the extraction script, you can pass the--module flag to update translations for a specific module.

All files are then bundled by the build process in a single[MODULE]-translations-bundle.js file.

We use a custom node script that runslighthouse for automated accessibility testing.

There are two ways of running the script:

• Development mode - it runs the accessibility audits on the local theme preview, on a specific account. It requireszcli themes:preview to be running;
• CI mode - it runs the accessibility audits on the live theme of a specific account.

Depending on the scope of testing, some manual testing might be needed in addition to the above.Tools likeaxe DevTools, screen readers e.g.VoiceOver,contrast checkers etc. can assist such testing.

To run the accessibility audits while changing the theme:

1. Start compiling and previewing changes like you normally would:

$yarn install$yarn start

2. Create a.a11yrc.json file in the root folder (seeexample);

   1. Specify the account/subdomain to preview the theme making sure it matches the activezcli profile
   2. Fillusername andpassword with the credentials of an admin user;
   3. Specify whichurls to test (if left empty, the script will test all urls);

3. In a separate console, run the accessibility audits in development mode:

yarn test-a11y -d

A11y audits will then run on the preview started in step1.

To run the accessibility audits on the live theme of a specific account, one must:

1. Install node modules:

yarn install

2. Setend_user_email,end_user_password,subdomain andurls as environment variables and run the accessibility audits in CI mode i.e.:

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

If there is a known accessibility issue that should be ignored or can't be fixed right away, one may add a new entry to the ignore list in thescript's configuration object. This will turn the accessibility issue into a warning instead of erroring.

The entry should include:

• the audit id;
• apath as a url pattern string;
• aselector as a string.

For example:

  custom:{    ignore:{      tabindex:[{path:"*",selector:"body > a.skip-navigation",},],aria-allowed-attr:[{path:"/hc/:locale/profiles/:id",selector:"body > div.profile-info"}]},},

In this example, errors for the audittabindex with the selectorbody > a.skip-navigation will be reported as warnings in all pages (*). The same will happen for the auditaria-allowed-attr with the selectorbody > div.profile-info, but only for the user profile page/hc/:locale/profiles/:id.

Please keep in mind that this should only be used when strictly necessarity. Accessibility should be a focus and a priority when making changes to the theme.

Pull requests are welcome on GitHub athttps://github.com/zendesk/copenhagen_theme. Please mention @zendesk/vikings when creating a pull request.

We useconventional commits to improve readability of the project history and to automate the release process. The commit message should therefore respect the following format:

<type>[optional scope]: <description>[optional body][optional footer(s)]

• type: describes the category of the change. Seesupported types.
• scope: (optional) describes what is affected by the change
• subject: a small description of the change
• body: (optional) additional contextual information about the change
• footer: (optional) adds external links, issue references and other meta-information

i.e.:

chore: automate releasefix(styles): fix button paddingfeat(script): add auto focus to fields with errors

We usehusky andcommitlint to validate messages when commiting.

We useGithub actions together withsemantic-release to release a new version of the theme once a PR gets merged. On each merge,semantic-release analyses the commit messages and infers a semantic version bump. It then creates a git tag, updates the manifest version and generates the correspondingchangelog.

The list bellow describes the supported commit types and their effect in the release and changelog.

Commits that add a breaking change should includeBREAKING CHANGE in the body or footer of the commit message.

i.e.:

feat: update theme to use theming api v2BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2

This will then generate a major release and add aBREAKING CHANGES section in thechangelog.

Bug reports must be submitted through Zendesk's standard support channels:https://www.zendesk.com/contact/