wordpress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.

Gutenberg

Welcome to the development hub for the WordPress Gutenberg project!

"Gutenberg" is a codename for a whole new paradigm in WordPress site building and publishing, that aims to revolutionize the entire publishing experience as much as Gutenberg did the printed word. Right now, the project is in the second phase of a four-phase process that will touch every piece of WordPress -- Editing, Customization, Collaboration (which includes Real-time collaboration, Asynchronous collaboration, Publishing flows, Post revisions interface, Admin design, Library), and Multilingual -- and is focused on a new editing experience, the block editor.

The block editor introduces a modular approach to pages and posts: each piece of content in the editor, from a paragraph to an image gallery to a headline, is its own block. And just like physical blocks, WordPress blocks can be added, arranged, and rearranged, allowing WordPress users to create media-rich pages in a visually intuitive way -- and without work-arounds like shortcodes or custom HTML.

The block editor first became available in December 2018, and we're still hard at work refining the experience, creating more and better blocks, and laying the groundwork for the next three phases of work. The Gutenberg plugin gives you the latest version of the block editor, so you can join us in testing bleeding-edge features, start playing with blocks, and maybe get inspired to build your own.

Check out the Keeping up with Gutenberg Index

Getting Started

Get hands on: check out the block editor live demo to play with a test instance of the editor.

Using Gutenberg

• Download: To use the latest release of the Gutenberg plugin on your WordPress site: install from the plugins page in wp-admin, or download from the WordPress.org plugins repository.

• User Documentation: See the WordPress Editor documentation for detailed docs on using the editor as an author creating posts and pages.

• User Support: If you have run into an issue, you should check the Support Forums first. The forums are a great place to get help. If you have a bug to report, please submit it to the Gutenberg repository. Please search prior to creating a new bug to confirm it's not a duplicate.

Developing for Gutenberg

Extending and customizing is at the heart of the WordPress platform, this is no different for the Gutenberg project. The editor and future products can be extended by third-party developers using plugins.

Review the Create a Block tutorial for the fastest way to get started extending the block editor. See the Developer Documentation for extensive tutorials, documentation, and API references.

Contribute to Gutenberg

Gutenberg is an open-source project and welcomes all contributors from code to design, and from documentation to triage. The project is built by many contributors and volunteers, and we'd love your help building it.

See the Contributors Handbook for all the details on how you can contribute.

To get up and running quickly with code contribution see Getting Started With Code Contribution. Also check out the other resources available on the Code Contributions page.

In whichever way you wish to contribute please be sure to read the Contributing Guidelines first.

As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our Code of Conduct.

Get Involved

You can join us in the #core-editor channel in Slack, see the WordPress Slack page for signup information; it is free to join.

License

WordPress is free software, and is released under the terms of the GNU General Public License version 2 or (at your option) any later version. See LICENSE.md for complete license.

gutenberg's Issues

Rogue text can be created while editing an image.

Not sure if this is a bug with contenteditable=true or what exactly, but it does lend to weird behavior.

You are able to create a raw text node within the editor by adding text below an image. No content block created for it. You could move the image up and down and create more rogue text nodes throughout the document.

One solutionish thing would be to scan the editor for text nodes when a block is selected, like:

// psuedo code
const findTextNodes = ( node ) => {
  return Array.from( node.childNodes ).filter( childNode => childNode.nodeName === '#text' );
}

textNodes = findTextNodes( queryFirst( '.editor' ) )

and then destroy the text node(s) and wrap it in a <p> instead.

Improve block inserter

If more options are available, changing the width of the .insert-block__menu feels like a better experience.

Connect text block controls (alignment)

These should change alignment at block level.

Buttons are not 100% Clickable

Details

The button is not clickable on the whole area where is highlighted on over, you only can click on the text or the icon.

To me this behavior can be a little confuse since the whole area is highlighted I assume the entire area is clickable.

Screenshot

Browser details

Expand image-block controls

Include full-width, parallax, etc.

Allow sorting blocks through Drag & Drop

The arrow will work fine for mobile, but for desktop, probably most users will want to sort blocks with a drag & drop approach.

Insert content between two blocks

Currently, the UI prototype shows the Plus to insert new blocks below the last paragraph (or the paragraph you're writing in). We should consider moving it to the side when you are on a new line. Here's a quick and dirty animatic:

Right after that, start typing and it converts into the type switcher, showing a paragraph block as selected.

This would also tie nicely into the #24, which would then invoke the plus dialog on the left.

This should inform how we can insert content between two blocks. Hover between two blocks to show a blue line and plus on the side:

Or, make a newline and insert, like you would at the end:

Cannot add Image using Chrome on OSX Sierra

1. go to https://wordpress.github.io/gutenberg/
2. click on image
3. click on image icon presumably to replace or add image
4. editing options close

OSX 10.12.3 Sierra, Chrome Version 55.0.2883.95 (64-bit)

Move focus of user when clicking to add content block

It's easy to not notice the selection panel when at bottom of a page. It doesn't load as it's off the screen. Found in Safari.

UI Prototype: Consider how far to take this

A lot of eyes on the prototype these days 🎉 !

A lot of tickets have been opened, noting the features the prototype are lacking (due to being dummy controls):

• #50
• #49
• #47
• #46
• #45
• #44
• #41

All this excitement around what was mainly a UI only prototype leads into the next question: where do we take this prototype from here? We've discussed creating two actual editor prototypes, one which uses TinyMCE as a parent of all blocks, one which uses TinyMCE as a child of each block. @iseulde has already done stellar work on the former here: https://iseulde.github.io/editor-blocks/

Could the UI prototype grow into the latter?

I can not create a new block with OS Sierra and Firefox 51.0.1

I can edit the words of the current block but I can not create a new one, no matter the type of block. Also I can not apply styles to the current blocks

Consider how editor interacts with other inline apps

I use PopClip which whilst a stress case, I thought it was interesting to share what happened with the editor when I interacted. I use this app to help with my dyslexia amongst other things - it has spelling checks and a ton of other features - it's not just for that use case but it works really well for a lot of people.

In showing these, I really like having the editor 'just where I need it'. We just may have to adjust that in relation to some of apps. I think there are quite a few that do similar. Whilst not by any means majority of users will use these apps, we should allow for them.

Figure out how to place controls for floated content

Cannot start a new paragraph or add an image on Android

Steps to reproduce:

1. Go to https://wordpress.github.io/gutenberg/ using an Android device.
2. Tap on the (+) menu at bottom left.
3. Try to tap on "Paragraph" to start a new paragraph.
4. Try to tap on "Image" to tap a new image.

Result: the controls to add new content blocks seem unresponsive. (19s)

Tested with Chrome on a Pixel with Android 7.1.1.

Consolidate TinyMCE Prototypes to Gutenberg UI

In an effort to properly compare all technical approaches evenly, we should migrate both single/multiple TinyMCE prototype approaches to use the latest Gutenberg UI.

/cc @aduth @iseulde https://github.com/iseulde/editor-blocks

“Select All” behavior

Should ⌘+A/Ctrl+A select only the current block or the whole text?

In the current prototype I am looking at, it selects the whole text.

Add Tabbed Interface to Insertion Block

The latest mockup of the Insertion Block shows a series of tabs along the top of the dialog ( Photos, Videos, Audio ):

This task involves building out support for the tabbed interface and possibly adding in some mock images to see how that experience might feel within the constraints of the Insert Block dialog.

Emojis are not copied.

🙌 The new editor for WP has a prototype and it needs your help. Let's test it. 💯
https://ahmda.ws/WP_Gutenberg
Let's make #WordPress editing experience better. ...

The text above was copied and paste to the editor.

A capture from the text used.

This was the result.

/ on a newline should open the insertion dialog

Slack style! Wouldn't that be cool?

Inline controls not working

Bold, Italic, Link, Strikethrough, etc not working for me on Chrome Version 55.0.2883.75 (64-bit) on OSX El Capitan

Heading block controls: show buttons to set heading size

From prototype testing:

“title” is an H (heading), but tagged as an H2 when I inspect the page source. What if I want an H1 or H3 etc?

https://make.wordpress.org/design/2017/02/09/initial-gutenberg-prototype-editor-testing/#comment-25060

TinyMCE formatting improvements

• Quip/Ulysses-like links — https://cloudup.com/cgXAgatVlps — a UI affordance showing the boundaries of the element, allowing you to know when the caret is inside the element vs. outside.
• Same as the above but for code blocks (through button or backticks).
• Spurious markup on blockquote when replacing content. (Ticket.)
• Option to strip all attributes on paste, except when pasting internally. (Added by @iseulde.)
• Fix some contenteditable=false bugs: tinymce/tinymce#3325. (Added by @iseulde.)
• Make sure we have good test coverage for pasting from Google Docs. https://github.com/tinymce/tinymce/blob/4.5.3/tests/plugins/paste.js#L217 (Added by @iseulde.)

https://core.trac.wordpress.org/component/TinyMCE
https://core.trac.wordpress.org/query?status=!closed&keywords=~upstream&component=TinyMCE

Spec out which blocks need which controls

F.ex. Headline won't need bold/italic inline controls, and Image might need some extra alignment controls, such as "full bleed". Let's start spec'ing out the most basic blocks, get those right, then we can add to it.

Text, or Paragraph

Base properties:

• Basic alignments
• Basic formatting
• Inline links

Advanced properties:

• Dropcap
• Alternate style for first line
• Responsive columns?
• Layout columns?
• Footnotes?

Heading

Base properties:

• Headline type/size

Advanced properties:

• Subheading?

Quote

Base properties:

• Basic alignments
• Basic formatting
• Surface cite attribute
• Stylish alignments

Advanced properties:

• Change between multiple quote styles
• Dropcap in quote?
• Caption?

Image

Base properties:

• Basic alignments
• Stylish alignments, like full-bleed, pull to the side, just wider than paragraph
• Surface caption

Advanced properties:

• Alt text, other metadata
• Parallax
• Fixed position/Fixed background
• Crop (maybe converts img to div with background?)
• If GIF, then show play/pause controls?

UI: Animate toolbars and block boundaries as they appear and disappear

The experience can be made nicer with non-intrusive (read: fast) animations. For example:

• Block level controls as well as the type switcher could animate out from "behind" the block in a .1s brief animation
• When you create a new block, the outlines should "pop out" in a satisfying elastic way

The idea is to make you feel productive as you type, same feeling as when you feel productive typing on a clicky keyboard.

Screen re-jiggers after tapping the + menu on Android

Steps to reproduce:

1. Go to https://wordpress.github.io/gutenberg/ using an Android device.
2. Tap on the heading content block at the top.
3. Scroll down and tap the (+) icon at the bottom left.

Result: a disorienting screen re-jigger happens. (24s)

Aside: this might be a "normal" Android thing? (I've recently switched from iOS to Android.)

Tested with Chrome on a Pixel with Android 7.1.1.

Implement block-switch menu

Multiple block selection

The user should be able to align/convert a selection over multiple paragraph blocks. I guess this could be solved by having one text block for multiple paragraphs, but how do you then align/convert a single paragraph? I thought it might be nice to be able to select multiple connecting paragraph blocks. Would love to see some discussion around this.

Add "caption" to image block example

Inline style pops up on highlight

From prototype testing:

I’m sure it’s just a fluke, but the inline style editing pops up when I highlight a word in another popup.

https://make.wordpress.org/design/2017/02/09/initial-gutenberg-prototype-editor-testing/#comment-25095

Show block controls on hover

The move up/down arrows should show when you hover over a block as well.

Add Additional Sections & Scrolling to Insertion Block

The insertion block design shows the notion of having "Sections" within each tab of the dialog:

This task is to add support for sections within the tabs, and populate with some example block icons. One section that could be added at this time would be for embeds and could display a list of popular services ( facebook, twitter, youtube, WordPress blog post etc ).

Firefox compatibility

As always, I get the great honor of reporting that some of this doesn't appear to work in Firefox, which is my primary browser. I use the developer edition.

Things that don't work as compared to Chrome:

• Up/down reordering
• Webfonts

Things that do:

• Image sizing / placement
• Text editing + new paragraph block

Things that don't work in either (assuming expected):

• Adding a new block beyond the ability to hit enter for a new paragraph block
• Filtering/searching of block types
• Text alignment

Add "Quote" block example with cite

Mobile UI for moving blocks, switching type, and formatting

Steps to reproduce:

1. Go to https://wordpress.github.io/gutenberg/ using an Android device.
2. Tap on a content block to select it.
3. Try to move the block to a new location.

Result: the options to move a block seem to be hidden off-left. (14s) I expected to be able to drag and drop the content blocks from an edit mode of some sort, as #38 suggests.

Tested with Chrome on a Pixel with Android 7.1.1.

Text format pop-over displays over block selector menu

It is especially weird when I selected some of the text on the menu itself and the pop-over displayed as if I could edit that:

(Sorry if my terminology is bad, couldn't remember exactly what the pop-over is called.)

Why not use querySelector instead of queryFirst

Looking into the code I found the usage of queryFirst but I believe querySelector already does this.

Returns the first Element within the document (from the docs)

Is there any reason to not use querySelector instead? I would like to create a PR with the changes if required.

Thank you.

Popup Toolbar: Show Also When Selecting Text With Keyboard

Hey, guys!
The prototype is looking great, I did some testing (macOS with Chrome) and here's what I think about it.

• Selecting text (with the keyboard) doesn't bring up the toolbar on macOS with Chrome — it appears when I click or click-drag-select.

---

---

• Selecting the text on Andriod with Chrome gives you the option of copy/paste and the toolbar kinda gets stays hidden behind it.

---

---

• When I Select-All and delete everything, the text becomes weirder.

---

---

• When I want to align the text, toolbar appears and the align icons are hidden behind it.

---

---

• I was not able to align the text. I think the align controls should be kept in the same toolbar instead of having the user go through three different ones?

---

---

• Image handling is pretty intuitive!

That's all for now :)

Fade out all outlines as you are typing

Take the UI prototype for a spin: https://automattic.github.io/gutenberg/ — put the cursor in a paragraph, make some linebreaks, write some text, soak it up.

It's not intended to be super functional, but rather to give a feel for how the block and inline level controls can work, and how that feels while typing. Depending on how far we want to take it, here are some thoughts on how the feel of it all could be improved.

Type selector + up/down rearrangement controls

Should we be showing these controls when you hover over a block? Right now only the faint outlines show up. Might be nice for some quick rearranging to not have to click first.

Show outlines in block you are typing in

Right now the faint outlines show only when you hover over a block with a mouse. Should we be showing these outlines as you are typing inside a block as well? (And only on that block?)

... OR: fade out all outlines as you are typing?

Related to hover outlines, instead of showing outlines on the block you are typing in, we could consider fading out all outlines as you are typing, even outlines on block that your mouse is currently over. The cursor itself fades out anyway, maybe the outlines should too?

When rearranging blocks, the block moved should stay is-selected.

Moving around blocks right now is neat, but a little disorienting. Perhaps we should even add a subtle animation showing the block moving to its new place, squishing out the old block.

Implement block insertion popover

Ability to highlight blocks that are wrapped by another block.

If enough wrapped text is added around an image block, it becomes no longer possible to access the images block level controls. Adding z-index to the image when in "left-aligned" or "right-aligned" will most likely alleviate that problem.

Option to delete or dublicate a block

I have been exploring some ideas around actions that users may want to perform to a block (apart from editing it). Such actions may be to clone (dublicate) a block, or delete it.

If there is indeed a need for this, which would be the best placement for those elements / icons to appear? Directly accessible (on hover) or nested inside the block menus?

Personally I believe they are crucial actions and they must more accessible. Should we perhaps extract a set of global actions that appeal to all blocks, and create a consistent UX for them?

I have added a draft of my work on this at inVision, with my comments, so if anyone wants to take a look and comment by point-and-click, feel free to do so (make sure you enable comments mode from the bottom right of the screen)

Here’s the link: https://invis.io/HYAGLFW8E#/219088646_TextBlockStates

Sorry, it’s all combined in one static image, and no interactivity for now.

What tools can be used?

Hi!

I was curious if there were any tooling limitations surrounding this project. I would like to be able to use es6 stuff, but wasn't sure if adding a build process, etc. was what this repository was all about. If a node.js build process, is not permitted, or if there is a future build process in mind, it would be nice to know what can be used or what potentially lies ahead. On top of build tools ( or lack thereof ), what unit testing stuff can be used?

No worries if this is not on the agenda at this time, but I would like to help out and having a bit of direction on what tools you like to use can help guide my contributions. For now I will do non es6, but it could get ugly 😄

Thank you!

Oddities in clicking behaviour

@mapk reported this here: https://make.wordpress.org/design/2017/02/09/initial-editor-blocks-prototype-editor-testing/#comment-25093

Found some clicking oddities with the inline style editing of the entire block, after clicking bold and then bold again, it got switched to a layout inline editor abruptly. Example gif below.

Simple API for defining a block

We need a simple tool to let us quickly define a block (root element, custom attributes) to speed up the prototyping.

Consider greying out arrows when makes sense

From prototype testing:

The topmost block has an up ordering arrow and the bottom on has a downward ordering arrow. These should be grayed out as they are not true options.

https://make.wordpress.org/design/2017/02/09/initial-gutenberg-prototype-editor-testing/#comment-25060

Keyboard shortcuts support

For accessibility and power-users both, we should always think about keyboard support. This was first brought up in #61, but deserves being fleshed out more.

The editor already has keyboard support for most formatting controls, including the "Paragraph" type switcher, which we are pondering moving to the side. Though since this will likely expand a fair bit beyond paragraphs, headings and preformatted, maybe that needs love too.

Many of these are existing keyboard shortcuts that should probably stay intact for back compat.

Inline formatting:

• Bold ⌘B
• Italic ⌘I
• Link/edit link ⌘K (or paste around selected text) Being handled in #4411.
• Unlink ^⌥S Being handled in #4411.
• Strikethrough ^⌥D Being handled in #4411.
• Change heading size ^⌥↑ for increase, ^⌥↓ for decrease See #71 (comment).

Hidden (?) controls:

• Undo ⌘Z
• Redo ⌘Y
• Cut ⌘X
• Copy ⌘C
• Paste ⌘V
• Select All ⌘A See #4369 now.
• Keyboard shortcuts cheat sheet — currently ^⌥H, should it instead/also be Shift ?
• Underline ⌘U
• Code ^⌥X Being handled in #4411.
• Align center ^⌥C
• Align left ^⌥L
• Align right ^⌥R
• Justify ^⌥J
• Bullets ^⌥U
• Ordered list ^⌥O
• Remove link ^⌥S Being handled in #4411.
• ⌘+ENTER (Ctrl+Enter for Windows) to create a separator

Markdown-esque shortcuts/syntactic sugar:

• Code: wrap text in backticks, `
• Bullets: * or - on newline
• Ordered list: 1. or 1) on newline
• Blockquote: > on newline
• H2-H6: ## - ###### on newline
• Horizontal line: --- on newline

Insertion/block level controls:

• Insert block: ^⌥M (for fallback) and / on newline (see #24)
• Move block up ^⌥↑
• Move block down ^⌥↓
• Open block type switcher ⌘~ then ↑/↓ and Enter for select
• Toggle between block types ~

Inserter:

• Invoked where the cursor is, by typing / on newline or pressing ^⌥M, then ↑/↓ and Enter for select

Consider making glyph symbol able to change type of block

From prototype testing:

When a block is selected, clicking the “glyph” (H, paragraph symbol) does nothing. I wish it allowed me to change the type of block, like changing a paragraph to a blockquote, for example.

https://make.wordpress.org/design/2017/02/09/initial-gutenberg-prototype-editor-testing/#comment-25060

Starting a sentence (or block) in bold, without the need to select text previously

I am wondering if it is worth pointing out that currently there is no way for a user to start typing in bold or italics right away without highlighting the text so for the toolbar to appear.

He can do this via keyboard and works quite well as I see here https://wordpress.github.io/gutenberg/ but there are many people out there who are not familiar with keyboard shortcuts for bold, and rely on the B and I icons.

Perhaps this is too much of a stretch at this point as there are more fundamental challenges to workaround, but it might be worth considering.

Render block-attributes on selection

Each block has specific attributes at block level.

Fitting image to whole view makes arrows disappear

From prototype testing:

This is a small problem, but I found that fitting the image to the whole view makes the up and down arrows disappear. It’s something that I haven’t seen mentioned in the comments so far.

https://make.wordpress.org/design/2017/02/09/initial-gutenberg-prototype-editor-testing/#comment-25109