The Block Editor

The Block Editor is designed to simplify the creation process, making adding content intuitive without keeping large toolbars on screen while you write. However, this does not mean that its functionality is diminished; with the block editor you can style and modify your text, insert media, galleries or video embeds, and adjust layouts and styles with just a few clicks. The block editor also gives you a visual representation of your content as you work. The final appearance depends on your theme, so use Preview to check how the post will look on your site.

The Block Editor Workspace

So what makes the Block Editor different from a regular editor or word processor? The key difference is that each paragraph of text, each list, and each image, gallery, video or other inserted media are placed into their own 'block' of space in the editor. This makes it easier to organise your content; instead of needing to copy and paste elements around the page to reorder your content, or add HTML tags to style it, you can just use the controls to move and style each individual block separately.

You can't actually see the majority of these controls when you start writing though; to keep the writing process clean and unobtrusive the options are hidden away until they're needed. With just a few clicks, you can add media, style content, and perform a multitude of other functions. But let's start with the basics:

Adding a Post Title

A post title is required before a post can be saved. When first loading up the block editor, you'll see a field marked Add post title; click on this and add your title text.

Creating Blocks

In a new post you'll see some placeholder text where the first block begins:

Click on the Start writing or press the TAB key to choose a block. text to place the cursor and start writing your first bit of content. To create a new paragraph block, press Enter when you finish the paragraph. Pressing Enter in the middle of a paragraph splits it into two blocks, while Shift + Enter adds a line break within the same paragraph. Other block types handle Enter differently; for example, it adds a list item in a list or a new line in a code block. Alternatively, hover your mouse cursor over a block and click the plus sign to its left, or press Tab in an empty paragraph, to open the list of block types. More details on the available block types can be found in the Insert Bar section later in this guide.

Modifying Content

The Block Editor in Publii provides all the functionalities that you'd expect from an editor, and more besides. However, unlike other editors that include extensive, intrusive toolbars at all times, the block editor's toolbars are hidden by default, opening only when needed. A key element of getting the most from the block editor is understanding where these toolbars are, what they do, and how to access them. For the sake of clarity, we will refer to these toolbars as the Insert Toolbar, the Conversion Toolbar, the Formatting Toolbar, and the Inline Editor.

The Insert Bar is used to create new blocks of any type, which will be inserted immediately after the current block. To open this toolbar, hover your mouse cursor over the block where you want to add the new block, then click the Plus icon to its left to open the list of block types. Clicking an option inserts a block of the selected type; if the current paragraph is empty, the new block replaces it.

The Conversion and Formatting Toolbars allow for content in an existing block to be modified at any time; useful if you change your mind during editing. The Formatting Toolbar will be especially important as we move through the various functions included in the Block Editor; if there are any feature-specific options, they will appear in this toolbar. To access these toolbars, you will need to select the block you wish to modify by hovering your mouse cursor over the block, then clicking on the Double Ellipses (six-dot) icon to the left of the block; this will highlight the block, and the toolbars will appear at the top-left and the top-right of the block.

Note: The Formatting Toolbar provides access to the majority of functions of a block; it is where you'll add images, modify layouts, or format text in a text-based block. Make sure that you are familiar with how to Select a Block by clicking the Double Ellipses (six-dot) icon that is visible when hovering your mouse cursor over a block, as this will be required when using the wealth of features available in the block editor.

Finally, the Inline Editor provides text formatting options such as adding bold or underline text, as well as links. To open the inline editor, highlight the text that you wish to modify and the inline editor will appear.

With that out of the way, let's take a look at the functions available in each of the toolbars.

The Insert Bar

A good post should include something other than just plain text, whether that's media such as images, galleries and video embeds, stylistic elements such as dividers, lists and a table of contents, or alternative text modes such as code, quotes and headings. In the Block Editor, these elements can be created using the Insert Bar. To see the insert bar, hover your cursor over the block where you want to add a new element, then click on the plus sign that appears to the left of the block to open the list of available elements:

Note: Each block type has specific options and functions that are unique to the block e.g. the image block has settings for adding and modifying images only, and cannot be used for code or other text-based content. For this reason, a new block should be created for each type of content that you want to add i.e. if you want a Heading followed by an image, you should first create a Heading block, then use the Insert Bar to add an Image Block after the Heading block.

When the insert bar is opened, it will display a Search for a block... field and a vertical, scrollable list of block types. The available options are, from the top:

• Insert a Paragraph block.
• Insert a Heading block.
• Insert an Image block.
• Insert a Gallery block.
• Insert a List block.
• Insert a Quote block.
• Insert a Table block.
• Insert a Code block.
• Insert an HTML block.
• Insert a Separator block.
• Insert a Read more block.
• Insert a TOC block.

The Paragraph option is hidden when you open the list from an empty paragraph. Read more is hidden once a read-more block has been added to the post.

In addition, you can use the following shortcuts. Type a shortcut or Markdown marker on its own in a paragraph block, then press Enter to convert it to the corresponding block:

Let's take a look at exactly what these functions do!

Search

The Search field can help you quickly find the block you need if you don't feel like scrolling through the list. Start typing a block type name into the search field, and the list of blocks will be dynamically filtered to immediately show you relevant results.

Paragraph

The first option, Paragraph, is a block for displaying basic text content, much like the sentence you are currently reading! This is the basic block type that you should use when you don't need to do anything special, just adding a regular text paragraph. Opening the Formatting Toolbar in a paragraph block will let you align text, add CSS classes to the paragraph, and other formatting functions. Full details of these options can be found in the The Conversion and Formatting Toolbars section further down the page.

Heading

The second option, Heading, inserts a heading block for adding titles and subtitles to your text. Properly structured headings make it easier for readers to follow the article and understand how its sections fit together.

Clicking on the heading option will, by default, insert an H2 heading, since the H1 is normally used for the post title. However, you may change your block to any heading from H1 to H6 using the respective icons in the Formatting Toolbar.

Inserting Images

The third option in the Insert Bar allows you to insert an Image into the block. Clicking on this option will create an image block, where you may drag and drop an image file into the upload area, or click Choose file to open your computer's file explorer and select a file.

Once a picture has been chosen it will be added to the block; at this point, there are multiple additional options available for styling and adding captions and other elements to the image.

To add a caption and alternative text to your image, select the block using the Double Ellipses icon, then enter your text in the fields underneath the image. Selecting the block also opens the Formatting Toolbar for styling your image.

Styling Your Image

There are also several styling options available via the Formatting Toolbar which let you decide exactly how you want the image to be displayed in your post.

The first three icons in the Formatting Toolbar for the image block let you choose Centred image, Wide image or Full-width image. The image will adjust in the editor as each option is chosen. The exact width on your published site depends on how your theme styles these options, so use Preview to check the result.

Creating a Link in the Image

You may wish to add a link to the image, rather than leaving it as a purely static element.

The chain icon in the formatting toolbar allows for the image to include a link to a different part of your site, to an external site, or to a specific file. To insert a link, open the formatting toolbar and click on the chain insert link icon.

Adding CSS Classes and IDs to the Image

For users that want to have more complete control over how the image is displayed by targeting it specifically in CSS, you may add a CSS class or an ID to the image block via the Advanced options gear icon in the formatting toolbar.

Clicking on the Gear icon will open the settings pop-up. From here, you can add your CSS class or ID into their respective fields, then click the Save button to close the pop-up and apply your changes.

Deleting an Image

If you decide that you don't want to use the image in your post anymore, you may delete it by clicking on the last icon of the formatting toolbar, the Bin icon. To prevent accidental deletion you will need to click on this icon twice before the image will be deleted; on the first click you will see the bin icon change color to red, then a second click will confirm deletion.

You can also remove just the image by hovering over it, then clicking the Bin icon in its top-left corner twice. This clears the image while leaving the block in place, so you can choose a replacement.

Inserting Galleries

The fourth option in the list of block types is the Gallery block. If you have a large number of pictures that you want to display, then a gallery offers a simple but elegant solution. Multiple pictures can be added to a gallery, which will be displayed in a column-style format that will adjust the position of the pictures automatically to fit the screen size effectively:

To create a Gallery, open the Insert Bar and click on the Gallery option. Just like when you are inserting a standard picture, an upload area will appear where you can drag and drop your files, or click Select files to choose your images via the file explorer.

Modifying the Gallery

By opening the Formatting Toolbar, you can access largely the same width options as when you are inserting a single image. There is also a Columns option, where you can select between one and eight columns. Selecting the gallery opens fields for each image's alternative text and caption, along with an upload area for adding more images. You can drag the images to change their order.

The Advanced options and Delete block controls apply to the whole gallery. To remove an individual image, close the block toolbar and click the bin icon on that image twice.

Lists

The fifth option in the list of block types allows you to insert a List block. A list can be unordered, which uses bullet points for each item, or ordered, which adds a number to each item, starting from one and ascending.

To insert a list block, open the Insert Bar and click on List. By default this creates an unordered list, but you can switch to an ordered list by selecting the block to open the Formatting Toolbar, then clicking Use ordered list; the icon looks like a list of numbers rather than bullet points.

After creating a list, the first bullet point or number will be added, ready for your text. To add more items to the list, press Enter while the cursor is in the list. Pressing Enter again on an empty final item returns you to a new paragraph block. You can use Backspace to delete text as normal. To create a nested list, select text in a list item and use the indent or outdent controls in the Inline Editor.

Quote

The sixth option in the list of block types inserts a Quote block. This block adds styling to highlight the text as a quote, and also adds an optional Quote author field. Note that the exact styling of the block will differ depending on the theme that you are using.

After clicking the quote icon, you will see a text area for the quotation and a Quote author field. Add the quote itself in the text area, and the attribution in the author field.

The Quote author field is optional, so you can also use the block to highlight a passage from your own article without adding an attribution.

Inserting a Table

The Table block lets you organise content into rows and columns. Open the Insert Bar and choose Table, or type /table in a paragraph block and press Enter. A new table starts with two columns, a header row and two body rows. Click in a cell to enter text.

When a cell is active, use the plus controls beside the table to insert rows and columns. The bin controls remove the selected row or column after a second click confirms deletion. Drag the boundary between columns to adjust their widths. In the Formatting Toolbar, Toggle header row and Toggle header column let you change whether the top row and first column are used as headers.

Press Tab or Shift + Tab to move between cells. Enter inserts a row after the current row, while Shift + Enter adds a line break within the current cell.

Displaying Code

The Code option creates a block for displaying code examples in your posts. Clicking on the icon will add a block with a Code Editor:

Inserting content into this editor is the same as when you are adding normal text. However, pressing enter in the code editor will not create a new block, instead, it will create a new line in the code editor, with each line being numbered for easier reading.

Setting the Code Language

By opening the Formatting Toolbar, you can set which programming language is used in the code block; this affects syntax highlighting in the editor and identifies the language in the generated HTML. The first option is Language. Open this searchable drop-down list and choose the language you wish to use, or select Plain text when no language is needed.

Converting a code block back into a regular Paragraph block removes its code styling. The result uses the paragraph styling provided by your theme.

Syntax highlighting in the editor does not automatically add a highlighter to your published website. To colour code examples on your site, install and enable the Syntax Highlighter plugin, or add your own syntax-highlighting scripts and styles.

Using HTML

The HTML block is used for inserting HTML content. As discussed earlier in The Publii Editors section of this guide, your post content needs to be converted to HTML to be displayed in browsers correctly. By choosing an HTML block, you can directly insert your own HTML code; useful if you need a specific tag or formatting that is not available through the other blocks. You can also paste video embed code here. Unlike a Code block, which displays a code example, the HTML block adds markup for the browser to render.

Inserting a Separator

The Separator option adds a divider, which can be used to separate paragraphs that are not directly connected thematically or to add an aesthetic touch to the page. Its Formatting Toolbar offers Wide line, Dots and Dot styles.

A divider will take up an entire block, and no additional text can be added.

Inserting a Read More Marker

The Read more block marks where the post's custom excerpt ends. Without this marker, Publii generates an excerpt using the length configured by your theme. When a read-more block is added, the content before it becomes the excerpt shown wherever the theme displays post summaries, such as on the homepage. This is helpful if your article begins with a short introduction and you do not want the summary to include part of the next paragraph. The marker itself does not add a button to the article; any read-more link in the post listing is provided by the theme.

To add a read-more marker to your article, open the Insert Bar and click Read more; the block will be added at the selected position.

Note: Only one read-more can be added into an article; once one has been added, the option will no longer appear in the list of available block types in the Insert Bar. Should you wish to move the read-more, you can click the up and down arrows that appear to the left of the block when it is selected to move it up and down in the block order, or delete the block entirely, allowing you to insert a new read-more block.

Inserting a Table of Contents

The last option in the Insert Bar is for inserting a TOC (Table of Contents) to your post. A table of contents can be a useful tool to help users find a specific part of your post, especially long-form posts with many sections, or documentation where users will not necessarily need to read the entire post to get what they need.

Generating a table of contents is largely automated in Publii; after clicking on TOC, an Add label field appears where you can define the title for your table. The list is generated automatically from the Heading blocks in your post, using their H1–H6 levels to show subsections. It updates as you edit the headings. Headings written inside an HTML block are not included.

The Inline Editor

Since the block editor is still at its core a word processor, it includes the standard text formatting options that you would expect, including:

• Change text to Bold.
• Change text to Italic.
• Add Underline to text.
• Strikethrough text.
• Insert and remove links.
• Format text as inline code.
• Highlight text.

These basic functions are provided by an inline editor, which opens automatically whenever a block of text is highlighted, or if you double-click on a word in a block:

The first four icons in the toolbar cover the basic formatting settings; starting from the left; adding bold, italic, underlined or strikethrough text. To use these options, use your mouse to highlight the block of text you wish to change, which will automatically display the inline editor. Then, click the appropriate icon to modify the text accordingly.

The marker icon also provides a basic formatting function: highlighting text. This adds a coloured background to the text to make it stand out. To add a highlight, select the text to bring up the inline editor, then click the marker icon. In a list block, additional indent and outdent controls appear after it.

The chain and curly braces icons offer options beyond basic text formatting. The curly braces apply inline code styling to the selected text, rather than converting the entire block as the Code option in the Insert Bar does. The chain icon is for inserting links; let's look at that now:

Inserting Links

The chain icon in the inline editor allows for your text to be converted to a link, so that users may click on it to be taken to a different part of your site, to an external site, or to a specific file. To insert a link, select the text that you want to convert to a link in your text, then click on the insert link icon in the inline editor. The Insert Link overlay will appear:

In the overlay, the tabs at the top allow you to choose what type of resource you want to link to, while the field in the centre allows you to select the resource. The available link types are:

• Custom - This option is for links that go to a URL that is most often external to your Publii site. If this option is selected, you should add the complete URL you wish to link to in the field in the centre of the overlay e.g. https://example.com. Also helpful for anchor links that take you to a specific place on the page.
• Post - This option creates a link to a specific post on your Publii site. After selecting this option, you can click on the drop-down list in the centre of the overlay to select a post. If you have a lot of posts, you can start typing to dynamically filter the list.
• Page - Similar to the Post option, this allows you to create a link to a specific static page on your Publii site. Select the target page from the drop-down list.
• Tag - This option links to a specific tag page on your Publii site, showing a list of posts attached to the tag. As with the post, you can select which tag page to link to in the drop-down list, or type to filter the results.
• Author - Just like the tag and post options, this option lets you link to an author page on your Publii site, showing a list of posts created by the specified author. Select which author you want to link to in the drop-down list.
• File - This option creates a link that allows users to view or download a file included in your website, such as a PDF, document or media file. If this option is selected, clicking on the field in the centre of the overlay will let you choose a file from the Publii File Manager; as with the other options, you can type to filter the visible results.

Once you have chosen a link type and set the target, you can set optional Attributes for the link. These are controlled via the fields and switches underneath the address field, with the following options available:

• Link "title" attribute - In this field, you can add text that browsers may display as a tooltip when a user hovers their mouse over the link. This is useful for providing extra context about the link's destination.
• CSS class - This field allows you to add one or more custom CSS classes to the link element, which can then be used to apply unique styling to the link with your own CSS code.
• Open in new window - Enabling this attribute opens the link in a new window or tab, rather than directing the currently-selected tab away from your site to the linked URL.
• Link "download" attribute - This attribute is only available when adding a File link, and tells the browser to treat the linked file as a download. The result can depend on the browser and server settings.
• rel="nofollow" - Use this when you do not want to endorse the linked page and the sponsored or ugc values do not apply. It does not prevent the destination page from being crawled or indexed through other links.
• rel="sponsored" - This marks links that are advertisements or paid placements, including affiliate links.
• rel="ugc" - This marks links in user-generated content, such as comments or forum posts.

If your link information is completed and your attributes set, then you can click on the Save option to finish creating the link.

Removing Links

To remove a link that you have created, double-click on the link in the post editor, or highlight the block of text to open the inline editor. You'll notice that there is a new icon available next to the insert link icon, displaying a broken chain. This is the remove link option, so click on that, and the text will be returned to normal.

The Conversion and Formatting Toolbars

As discussed earlier in this guide, clicking the Double Ellipses icon to the left of a block displays additional toolbars for modifying its content. The Conversion Toolbar, where available, is located at the top-left of the block beside Convert to:. The Formatting Toolbar is at the top-right, providing text formatting and other block-specific controls. The Insert Bar remains available for adding blocks after existing content; it is not limited to empty blocks.

Since some of the functions here are duplicated from the Insert Bar you may already be familiar with many of the functions in these toolbars, but for the sake of clarity we will cover each function in full.

Note: The available conversions and formatting controls depend on the block type. Paragraphs, headings, lists, quotes and code blocks have different conversion options. Image, gallery and table blocks have their own controls instead of the paragraph conversion toolbar.

For a Paragraph block, the available options in these toolbars, from left to right, are:

Conversion Toolbar

• Convert the block to a Heading
• Convert the block to a Quote
• Convert the block to a List
• Convert the block to Code
• Convert the block to HTML

Formatting Toolbar

• Align Text to the left
• Align Text to the centre
• Align Text to the right
• Clear formatting from the block
• Advanced options
• Delete Block

Let's look more closely at formatting functions:

Aligning Text

If you are using the standard paragraph style for your block, the first three icons in this section are for aligning your text on the page. To align text to the left (default), centre or the right, click on the respective icon in the toolbar.

Removing Formatting

The Clear formatting icon, which looks like an eraser, removes inline text formatting from a paragraph, such as bold, underline or strikethrough. It does not change the block type. Other block types, including lists and quotes, also provide this control where appropriate. To convert a supported text block back to a paragraph, click Paragraph in its Conversion Toolbar.

Advanced Options

The Advanced options gear icon opens the block's settings pop-up. Here, you can add CSS classes and an ID, along with any options specific to that block type.

For a paragraph block, the settings include CSS class and ID fields, where you can enter values to target the block with your own CSS. The centre option, Paragraph style, provides the following styles. Their appearance on the published site depends on your theme:

• Info - Styles the block to an info box.
• Highlight - Highlights the block to draw attention to the contents.
• Success - Styles the block as a success message.
• Warning - Styles the block as a warning message.

Heading blocks also have a Use custom ID switch. Enable it to enter your own heading ID instead of using the automatically generated value.

Delete Block

The last icon in the Formatting Toolbar, which looks like a bin, is for deleting the block entirely. To ensure that blocks are not deleted accidentally you will need to click on this icon twice to confirm deletion.

Moving Blocks

One of the benefits of the block editor is that it allows you to reorder the blocks, moving them up or down on the page to get your layout just right. To reorder blocks, first click on the Double Ellipses (six-dot) icon to open the toolbars. Then, click on the up and down arrows to the left of the block to move the block up or down in the hierarchy.

Bulk Editing Blocks

If you've added a lot of content to your post, then using the regular duplication, deleting and reordering options may be too slow and unwieldy. In such cases, you can take advantage of the Bulk Edit sidebar to quickly rearrange the order of the blocks on the post, or duplicate and delete existing blocks from one place.

To open the Bulk edit panel, click Bulk edit at the bottom-left of the block editor window. This opens a panel listing the blocks in the current post, along with controls for duplicating and deleting them:

From here, you can perform three useful functions:

Reorder Blocks

To reorder the content blocks in your article, in the list of blocks in the left-sidebar, drag and drop the block you wish to move to its new position in the order; it will be inserted wherever you drop the block in the list, pushing all the following blocks one step down.

Duplicate a Block

To duplicate a block, click the double-square icon to the right of the block you wish to copy in the bulk editor; a copy will be created immediately below the selected block, ready to be dragged to wherever you need it. The duplicate control is disabled for Read more, since a post can contain only one read-more block.

Deleting a Block

To delete a block via the bulk edit sidebar, click on the Trash icon to the right of the block that you wish to delete two times; on the first click the icon will change, and a second click confirms the deletion.