{"id":20825825,"url":"https://github.com/upstatement/ups-editorial-wp-plugin","last_synced_at":"2025-07-16T18:32:42.895Z","repository":{"id":66349991,"uuid":"323430878","full_name":"Upstatement/ups-editorial-wp-plugin","owner":"Upstatement","description":"A plugin for customizing the editor experience to suit Upstatement-built WordPress projects.","archived":false,"fork":false,"pushed_at":"2023-02-23T23:00:45.000Z","size":2334,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-16T16:10:34.739Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Upstatement.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-12-21T19:35:56.000Z","updated_at":"2023-11-08T22:53:38.000Z","dependencies_parsed_at":"2025-05-09T16:32:22.896Z","dependency_job_id":null,"html_url":"https://github.com/Upstatement/ups-editorial-wp-plugin","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Upstatement/ups-editorial-wp-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Upstatement%2Fups-editorial-wp-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Upstatement%2Fups-editorial-wp-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Upstatement%2Fups-editorial-wp-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Upstatement%2Fups-editorial-wp-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Upstatement","download_url":"https://codeload.github.com/Upstatement/ups-editorial-wp-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Upstatement%2Fups-editorial-wp-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265530657,"owners_count":23783128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T23:06:53.738Z","updated_at":"2025-07-16T18:32:42.847Z","avatar_url":"https://github.com/Upstatement.png","language":"JavaScript","readme":"# Upstatement Editorial\n\nA WordPress plugin for enhancing the editorial experience, including some common customizations for the [Gutenberg](https://wordpress.org/gutenberg/) editor.\n\n## Table of Contents\n\n- [What This Plugin Does](#what-this-plugin-does)\n  - [Blocks](#blocks)\n  - [Editor Plugins](#editor-plugins)\n  - [Core Enhancements](#core-enhancements)\n- [Theme Configuration](#theme-configuration)\n- [Theme API](#theme-api)\n- [Troubleshooting](#troubleshooting)\n- [Local Development](#local-development)\n- [Resources](#resources)\n\n## What This Plugin Does\n\nThe purpose of this plugin is to tailor the Gutenberg editor experience to be better suited to editors using their WordPress theme and to add functionality common to many websites. Features added as a part of this plugin fall into three categories: block modifications, editor plugins, and core enhancements. This plugin also exposes some global functions that can be used in theme templates.\n\n### Blocks\n\n#### Extended Blocks\n\nThe following blocks are extended typically at the registration hook (`blocks.registerBlockType`) to limit the number of available options for an editor. Some blocks also hook into the edit lifecycle (via the `editor.BlockEdit` hook) to add additional classes and structure to the editor markup so as to be able to control certain aspects of the block's settings with css.\n\n- [Cover](./src/blocks/extends/cover/index.js)\n- [File](./src/blocks/extends/file/index.js)\n- [Gallery](./src/blocks/extends/gallery/index.js)\n- [Image Layout](./src/blocks/extends/image-layout/index.js)\n- [Related Articles](./src/blocks/extends/related-articles/index.js)\n- [Table](./src/blocks/extends/table/index.js)\n- [Video](./src/blocks/extends/video/index.js)\n\n\u003e Note that you can continue to extend core block functionality in your theme by using WordPress's [blocks.registerBlockType](https://developer.wordpress.org/block-editor/developers/filters/block-filters/#blocks-registerblocktype) and [editor.BlockEdit](https://developer.wordpress.org/block-editor/developers/filters/block-filters/#editor-blockedit) filters.\n\n### Editor Plugins\n\nOur main Gutenberg \"plugin\" adds two panels to the main sidebar of posts: the Article Topper \u0026 Authors panels.\n\n#### Article Topper Panel\n\nThe article topper panel controls article post metadata concerned with the article topper. This includes:\n\n- `Topper type`: The look and feel of the topper, be it text-only or a site-width featured image\n- `Navigation theme`: When paired with dark background image toppers, an already dark-themed nav can appear invisible. This option allows for lighter navigation themes\n- `Overline`: Choose a primary category for your article to allow for better recirculation amongst common themes\n\n#### Authors Panel\n\nThe Authors panel allows editors to assign multiple authors to the author byline. This process starts with the `Authors` section under `Posts`, where you can create author profiles.\n\nThese authors also serve as taxonomies for your articles, so archive pages full of an author's own content are auto-generated on your behalf.\n\n### Core Enhancements\n\n- Adds a `Credit` field to attachment posts.\n\n### Template functions\n\nThis plugin exposes a few functions that can be used to retrieve relevant values handled by the plugin. See the [Theme API](#theme-api) section for information about the available functions.\n\n## Theme configuration\n\nBy default, all features of this plugin are enabled once the plugin is activated. However, you are able to configure the plugin's functionality (including disabling certain features) via a configuration file that can be added to your theme.\n\nTo set up a configuration file, add a `ups-editorial.php` file to your theme's root that returns an array containing the relevant configuration options:\n\n```php\n\u003c?php\n/**\n * Configuration for the ups-editorial plugin.\n */\n\nreturn array(\n  'author_panel'         =\u003e true,\n  'article_topper_panel' =\u003e true,\n  'attachment_credit'    =\u003e true,\n  'extended_blocks'      =\u003e array(\n\t\t'cover',\n\t\t'file',\n\t\t'gallery',\n\t\t'image-layout',\n\t\t'related-articles',\n\t\t'table',\n\t\t'video',\n\t),\n  'enable_block_styles'  =\u003e array(),\n);\n```\n\n### Configuration\n\n#### `author_panel`\n\n**Allowed types:** `boolean`\n\n**Default value:** `true`\n\nEnable or disable the plugin's `Author` taxonomy, as well as the Gutenberg editor panel containing the mechanism to add and manage authors for an individual post.\n\n#### `article_topper_panel`\n\n**Allowed types:** `boolean`\n\n**Default value:** `true`\n\nEnable or disable the registration of fields for article toppers and the Gutenberg panel that controls those fields.\n\n#### `attachment_credit`\n\n**Allowed types:** `boolean`\n\n**Default value:** `true`\n\nEnable or disable the registration of a `credit` field for attachments.\n\n#### `extended_blocks`\n\n**Allowed types:** `array`\n\n**Default value:**\n\n```php\narray(\n  'cover',\n  'file',\n  'gallery',\n  'image-layout',\n  'related-articles',\n  'table',\n  'video',\n)\n```\n\nA list of blocks that are extended by the plugin. To disable the extension of a certain block, exclude it from this array.\n\n#### `enable_block_styles`\n\n**Allowed types:** `array`\n\n**Default value:** `array()`\n\nWordPress core includes style options for some core blocks. This plugin removes those style options by default, but this parameter can be used to re-enable the core style options for specific blocks. The following blocks have core styles that can be re-enabled via this parameter: `button`, `image`, `quote`, `separator`, `table`.\n\n## Theme API\n\nThere are a few globally-available functions that can be used by your theme to retrieve data defined by this plugin's functionality. These functions are defined in the `Template.php` file at the root of the plugin directory, and exist under the `Upstatement\\Editorial` namespace.\n\nIt is recommended that your theme implement these functions wrapped by a `function_exists` check to prevent undefined errors in the case that the plugin is disabled. For example:\n\n```php\nif ( function_exists( 'Upstatement\\Editorial\\get_post_authors' ) ) {\n  $authors = \\Upstatement\\Editorial\\get_post_authors();\n  ...\n```\n\n### `get_post_authors`\n\n```php\nget_post_authors( WP_Post $post = null, string $field = null) : array | null\n```\n\nRetrieve a list of authors for a post.\n\n#### Parameters\n\n**`post`**\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Post to retrieve authors for. Leave blank to use the current global post.\n\n**`field`**\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;The field to return for each author. This can be any property from a WP_Term object. Leave blank to return the entire WP_Term object.\n\n#### Return\n\nReturns an array consisting of author data. If **`field`** is blank, this will be an array of `WP_Term` objects. If a **`field`** is specific, this will be an array of values for that field.\n\n### `get_post_overline`\n\n```php\nget_post_overline( WP_Post $post = null ) : WP_Term | null\n```\n\nRetrieve the overline category for a post.\n\n#### Parameters\n\n**`post`**\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;Post to retrieve the overline for. Leave blank to use the current global post.\n\n#### Return\n\nReturns the `WP_Term` object of the category term identified as the overline, or null if none is set.\n\n## Troubleshooting\n\n### \"I've updated the content in the Editorial sidebar, but it's not appearing in the preview.\"\n\nThis is a known issue with Wordpress Gutenberg where post meta doesn't save until the `Update` button is pressed. We're currently tracking the main issue at [WordPress/gutenberg#14900](https://github.com/WordPress/gutenberg/issues/14900), but until then you can try one of the following steps:\n\n- After updating the sidebar content, press the `Update` button and then the `Preview` button.\n\n- Press the `Preview` button twice. Sometimes the meta is only available for every-other preview.\n\n- Attempt a hard refresh in the preview window (\u003ckbd\u003ecommand\u003c/kbd\u003e+\u003ckbd\u003eshift\u003c/kbd\u003e+\u003ckbd\u003eR\u003c/kbd\u003e in Google Chrome).\n\n### Block validation and recovery\n\nWhen changing the saved markup of existing or new components, you are likely to come across an issue with block validation.\n\nThis error occurs when the markup of a block on last save doesn't match the markup of the block when it loads within the editor.\n\nIf this error was intentional, the easiest way to bypass the issue is:\n\n1. In the top right corner of the block, press the three dots.\n\n2. Select the `Attempt block recovery` option. This will re-render the block markup according to the latest version of the save function.\n\n3. `Update` the post to save the latest block markup.\n\nIf the error was unintentional, your console will be the best place to identify what went wrong. That may look something like this:\n\n```html\nBlock validation: Block validation failed for `ups/image` Content generated by `save` function:\n\n\u003cfigure class=\"wp-block-image\"\u003e\n  \u003cimg src=\"/good-image.png\" alt=\"A good image\" /\u003e\n  \u003cfigcaption\u003eThis is the caption\u003c/figcaption\u003e\n  \u003ccite\u003eThis is a new citation\u003c/cite\u003e\n\u003c/figure\u003e\n\nContent retrieved from post body:\n\n\u003cfigure class=\"wp-block-image\"\u003e\n  \u003cimg src=\"/good-image.png\" alt=\"A good image\" /\u003e\n  \u003cfigcaption\u003eThis is the caption\u003c/figcaption\u003e\n\u003c/figure\u003e\n```\n\n\u003e In the case above, there was a new `cite` element added to the markup after the block was already saved to the post. At this point you can either (1) choose the `Attempt block recovery` option to update the markup, (2) remove and recreate the block, or (3) revert the save function to remove the `cite` element.\n\n## Local Development\n\nTo make changes to this plugin, you can download this repository and add it to the `plugins/` directory of any running WordPress instance. You'll also need to perform some setup steps to ensure that you have all the built dependencies:\n\nTo start working locally, you'll need the following things on your machine:\n\n- [nvm](https://github.com/nvm-sh/nvm) to manage the Node version this project is running on.\n- [composer](https://getcomposer.org/) to manage PHP dependencies and autoloading.\n\nOnce the above are installed, you can get set up with the following steps:\n\n1. Ensure you're running the expected version of Node:\n\n   ```shell\n   nvm install\n   ```\n\n2. Install Node dependencies:\n\n   ```shell\n   npm install\n   ```\n\n3. Install composer dependencies and generate autoloaders:\n\n   ```shell\n   composer install\n   ```\n\n4. Watch the plugin files for changes:\n\n   ```shell\n   npm run start\n   ```\n\nYou can build the static front-end assets at any time with the following script:\n\n```shell\nnpm run build\n```\n\n## Resources\n\nDuring the development of this plugin, we found the following resources to be useful:\n\n- [Block editor overview](https://wordpress.org/support/article/wordpress-editor/)\n- [List of core blocks](https://wordpress.org/support/article/blocks/)\n- [Block design best practices](https://developer.wordpress.org/block-editor/designers/block-design/)\n- [Block editor developer tutorials](https://developer.wordpress.org/block-editor/tutorials/)\n- [Block editor components](https://wordpress.github.io/gutenberg/?path=/story/docs-introduction--page)\n- [Gutenberg developer documentation](https://developer.wordpress.org/block-editor/developers/)\n- [Gutenberg GitHub repository](https://github.com/WordPress/gutenberg)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fupstatement%2Fups-editorial-wp-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fupstatement%2Fups-editorial-wp-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fupstatement%2Fups-editorial-wp-plugin/lists"}