H2 is the internal communications tool for Human Made.
H2 is a WordPress theme, inspired by the design and principles of P2 by Automattic.
(Also check out the contributing documentation.)
This repository is provided as-is as open source, and we do not provide support for running it yourself. We recommend forking the repository for your own usage.
H2 is a standalone WordPress theme you can activate on any site, and is a drop-in replacement for P2. You can add additional functionality by activating the companion plugins, which H2 will automatically detect and use.
The release and release-develop versions of the H2 theme are built using GitHub Actions. Any time a pull request is merged into the main or develop branches, that code is built and pushed to the corresponding release and release-develop branches. You should not commit to the release branches directly, nor submit pull requests against them.
Development workflow:
- Implement a feature or bugfix in a feature branch created off of
main - Submit a pull request from that feature branch back into
main, and get code review - Merge the feature branch into
developmanually.- The
release-developbranch will be automatically rebuilt
- The
- Update the development environment to reference the newest built version of the
release-developbranch, to deploy and test the theme PR. - Once approved, merge the pull request into
main- The
releasebranch will be automatically rebuilt
- The
- Update the production branch
composer.jsonin the main network repository to reference the newest built version of thereleasebranch, to deploy the change to production.
The fastest way to see H2 in action is WordPress Playground — no Docker or local setup required. Launch the H2 demo to get a temporary site in your browser with the theme active and demo content seeded.
You can also run Playground locally: npm run playground:demo runs the same demo, and npm run playground runs your working copy of the theme (run npm run build first). See .playground/README.md for details.
The easiest way to try out H2 is using wp-env, which sets up a local WordPress environment with Docker.
Prerequisites:
- Docker Desktop installed and running
- Node.js 14 or higher
Setup:
- Clone this repository:
git clone git@github.com:humanmade/h2.git h2
cd h2- Install dependencies:
npm install- Start the WordPress environment:
npm run wp-env:startThis will:
- Download and set up WordPress 6.4
- Install the required Asset Loader plugin
- Map the H2 theme to the WordPress installation
- Start the environment at http://localhost:8888
- Build the theme assets (in a new terminal):
npm run build- Log in to WordPress:
- URL: http://localhost:8888/wp-admin
- Username:
admin - Password:
password
- Activate the H2 theme:
- Go to Appearance > Themes
- Activate "H2"
- Start the development server for live reloading:
npm startUseful wp-env Commands:
npm run wp-env:stop # Stop the environment
npm run wp-env:start # Start the environment
npm run wp-env:destroy # Remove the environment completely
npm run wp-env:logs # View WordPress logs
npm run wp-env:cli # Run WP-CLI commands (e.g., npm run wp-env:cli -- theme activate h2)If you prefer to use your own WordPress development environment:
You'll need a WordPress development environment. If you don't have one, set up a local Altis environment.
Clone this repository into your themes directory:
git clone git@github.com:humanmade/h2.git h2Once the checkout is complete, cd into the cloned theme directory, install npm modules, and start the development server:
npm install
npm start
H2 uses humanmade/asset-loader to integrate with Webpack. If you are running H2 within Altis, the Asset Loader will be available already. If not, install and activate the asset-loader plugin (humanmade/asset-loader if installing with Composer) before trying to run H2.
H2 will load the assets from the Webpack DevServer (npm start) if it is running. If the DevServer is not running, H2 will look for a production build and load those assets. If you see a white screen after activating H2, run npm run build to generate a production-ready static file bundle.
Editor styles require the editor CSS to be present on disk, which is complex to achieve when using the DevServer. If you are working on or testing block editor styles, run the production build in watch mode:
npm run build -- --watchFor production, deploy H2 as a regular theme. You'll also need to build the assets for H2, as we don't release prebuilt versions.
As part of your deployment process, run the .build-script shell script in the root directory. This will install the Node dependencies and build the static assets ready for deployment.
The build expects to be run using Node version 12.
H2 supports emoji reactions, but requires an additional plugin to provide the custom comment type and REST API endpoints.
Install and activate the H2 Emoji Reactions plugin to get started.
H2 supports hovercards to preview data for users on your network.
To enable Hovercards, you'll need to have a MAPBOX_KEY PHP constant defined in your environment. You will also need the Global Facts plugin.
It is easiest to test Hovercards when using an H2 network database backup. If not, you may need to add development code to map your local users to Global Facts user profiles.
H2 includes a site selector in the sidebar to facilitate using networks of H2 sites.
Install and activate the H2 Site Selector plugin. This must be activated network-wide.
Once the plugin has been activated, access the Settings > H2 Sites page in your Network Admin to enable and disable sites.
H2 includes support for GitHub-style markdown checklists when writing posts from the frontend, but it also supports the todo-list-block plugin for authoring todo lists within the block editor.
Created by Human Made. Licensed under the GPLv2+.
Uses ideas and concepts from P2 by Automattic. Licensed under the GPLv2+.
Support for Gravity Forms is derived from Gravity Forms Iframe Add-On by Brady Vercher. Licensed under the GPLv2+.