vocabulary-theme

WordPress Theme implementation of the Vocabulary design system (creativecommons/vocabulary).

Code of conduct

CODE_OF_CONDUCT.md:

The Creative Commons team is committed to fostering a welcoming community. This project and all other Creative Commons open source projects are governed by our Code of Conduct. Please report unacceptable behavior to conduct@creativecommons.org per our reporting guidelines.

Contributing

See CONTRIBUTING.md.

Development

The theme development work should be done within the src/ directory.

Setup

1. Create the .env file:

   cp .env.example .env

2. Update .env to set desired values for variables (WP_VERSION, WP_MOD_TYPE, WP_MOD_NAME, etc.)
3. Build/start Docker:

   docker compose up

4. Wait for build and initialization to complete
5. Install WordPress initially through the GUI (localhost:8080)
   • TODO: automate this step

Shortcodes

The theme comes with a custom [list] shortcode for displaying a list of queried objects that builds from a simplified WP Query obj

The shortcode operates as follows:

[list cat="category" tag="tag,tag,tag" type="post" limit="10" sort="ASC" sortby="date" template="blog_posts"]

The most minimal usecase:

[list]

The defaults are as follows:

• category:
• tag:
• type: post
• limit: 5
• sort: ASC
• sortby: date
• template: default

The template can be set to a custom partial, loaded from the shortcode-templates folder, if no template is set, it will instead display as the default template (a bulleted list of links)

The arguments accept the counterpart values from the subset of args in the WPQuery Class. This means that the category and tag arguments can be a single or comma separate list of values. sort maps to order and sortby maps to orderby for some beneficial UX for endusers to be more clear in purpose.

Chooser

The basic english specific UX is contained upstream within the creativecommons/chooser repository. Further dynamic functionality that goes beyond the pathway selection interactivity provided by HTML, CSS, and JS alone is handled by vocabulary-theme via PHP and WordPress's internal handling of i18n. Currently this dynamic functionality is utilized to provide translation support for the Chooser through Transifex.

1. The source .pot file is generated from wpcli (pulled from the wrapped strings in static-chooser.php): wpcli i18n make-pot . languages/vocabulary-theme.pot --domain=chooser, afterward the wordpress theme specific meta value strings like "theme name, description, etc." need to be manually deleted (TODO: automate this later, as wpcli lacks an option to exclude them at current)

2. The file is read through Transifex via the transifex.yml config, and loaded in for manual translation within the Transifex editor, wherein an end-user can select an available language to begin a translation from the source (en)

3. Once a translation is ready, Transifex can generate a language specific .po file, which is sync'd with GitHub via the GH Integration. The relevant <lang>.po file is added to the src/languages folder. It is important that the .po file in question not have a theme or textdomain specific prefix, as WordPress will not recognize the file otherwise.

4. Once Transifex has reached an appropriate translation threshold and fired off the integration for .po generation, it will create a relevant PR, which can be approved, and merged.

5. wpcli can then be used to generate a corresponding .mo file: wpcli i18n make-mo languages/. This can then be added a PR or appended to the PR created via Transifex.

6. Logic within the theme should now allow the newly added <lang> to be selectable within the available translation dropdown, which operates by setting the lang parameter in the URI. EX: ?lang=en_US

7. If a valid .mo file is found to match the set lang parameter, then the appropriate language translation is loaded, otherwise it will default to the original source (en). The dropdown will not appear if only english is present.

Docker containers

The docker-compose.yml file defines the following containers:

1. vocabtheme-wordpress-web (localhost:8080)
2. vocabtheme-wordpress-db
3. vocabtheme-composer
4. vocabtheme-phpmyadmin (localhost:8003)
5. vocabtheme-wpcli

Releases

See scripts/README.md.

Cache warning

⚠️ WARNING: This theme does not currently contain any dynamic content (any user-specific content). The addition of dynamic content must be coordinated with the content delivery network (CDN) page rules that govern what is cached.

Currently, the theme's output of pages is completely deterministic. Any given page rendered now, will be identical to the same page rendered 30 minutes later (assuming the theme is the same version). This allows for very simple CDN page rules (ex. Caching Static HTML with WordPressWooCommerce · Cloudflare Support docs).

Copyright and trademarks

CC Badge, Icons, Images, and Logos

• The badges, icons, images, and logos contained within this repository are for use under the Creative Commons Trademark Policy (see Policies - Creative Commons).
• The icons, images, and logos are not licensed under a Creative Commons license (also see Could I use a CC license to share my logo or trademark? - Frequently Asked Questions - Creative Commons).

Code

Vocabulary Theme code is licensed under the GNU General Public License v2.0 or later.

Vocabulary

COPYING: All the code within Vocabulary is dedicated to the public domain under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication.

Normalize.css

normalize.css is licensed under the Expat/MIT License.

Fonts

CC Accidenz Commons

CC Accidenz Commons by Archetypo is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) License.

JetBrains Mono

JetBrains Mono is licensed under the OFL-1.1 License.

Roboto Condensed

Roboto Condensed by Christian Robertson is licensed under the Apache License, Version 2.0.

Source Sans Pro

Source Sans Pro by Paul D. Hunt is licensed under the Open Font License.

Vocabulary Icons

Vocabulary Icons use icons from Font Awesome which are licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) License.