govspeak-visual-editor

Govspeak visual editor

This repo demonstrates how ProseMirror could be used to build a visual editor for Govspeak.

Govspeak is a flavour of Markdown used for publishing content on GOV.UK.

Local development

1. Clone this repo

2. Install dependencies

   npm install
   

3. Run the development server

   npm run dev
   

4. Open the example editor

5. Run tests

   Unit tests

   npm run test
   

   e2e tests

   npm run e2e-test
   

Editor overview

The editor implements a schema based on the prosemirror-schema-basic and prosemirror-schema-list modules, extended with some Govspeak-specific nodes (such as callouts).

It also builds upon the prosemirror-example-setup package which provides a basic editor UI and some useful configuration defaults.

Govspeak-specific nodes

You'll find custom Govspeak-specific nodes defined in the src/nodes directory.

Each 'node' file in that directory defines a few things:

1. A NodeSpec, which describes the node's schema for use with the prosemirror-model module
2. Input rules, which enable users to type Markdown-esque syntax to create nodes using the prosemirror-inputrules module
3. A buildMenu function which can add custom buttons to the toolbar menu provided by the prosemirror-example-setup module.

Making changes

You should keep track of relevant unreleased changed by adding to the "Unreleased" section of the CHANGELOG.md.

Publishing to npm

1. Checkout main and pull latest changes.

2. Create and checkout a new branch (release-[version-number]). The version number is determined by looking at the current "Unreleased" changes in CHANGELOG and updating the previous release number depending on the kind of entries:

• Breaking changes corresponds to a major (1.X.X) change.
• New features corresponds to a minor (X.1.X) change.
• Fixes corresponds to a patch (X.X.1) change.

For example if the previous version is 2.3.0 and there are entries for Breaking changes then the new release should be 3.0.0.

See Semantic Versioning for more information.

1. Update CHANGELOG.md "Unreleased" heading with the new version number and review the latest commits to make sure the latest changes are correctly reflected in the CHANGELOG).

2. Update package.json version with the new version number.

3. Run npm install to ensure you have the latest dependencies installed.

4. Commit changes. These should include updates in the following files:

• CHANGELOG.md
• package.json
• package-lock.json

1. Create a pull request and copy the changelog text for the current version in the pull request description.

2. Once the pull request is approved, merge into the main branch. This action will trigger the CI to publish the new version to NPM. A dependabot pull request will automatically be raised in relevant applications.

Custom events

The following events are emitted from the Visual Editor. Add event listeners to any parent wrapper to implement behaviour in response to these actions (e.g. for tracking purposes.)

• visualEditorButtonClick - emitted when a button is clicked in the toolbar. Details sent with the event can be accessed via:
  • event.detail.buttonText which returns the title of the selected button
• visualEditorSelectChange - emitted when select values change on dropdowns in the toolbar. Details sent with the event can be accessed via:
  • event.detail.selectText which returns the text of the selected option in the dropdown