CKEditor Ecosystem Documentation
Search
Contribute to this guide
Home/CKEditor 5/Features

Bookmarks

The bookmarks feature allows for adding and managing the bookmarks anchors attached to the content of the editor. These provide fast access to important content sections, speed up the editing navigation and contribute to a more efficient content creation.

# Demo

Use the bookmark toolbar button Add bookmark in the editor below to see the feature in action. Or use the “Insert” command from the menu bar to add a bookmark. Add a unique name to identify the bookmark (for example, Rights).

To use the bookmark as an anchor in the content, add a link Add link and put the bookmark name as target. In the example below it would be #Rights. You can change the bookmark’s name or remove it by clicking the bookmark icon inside the content. A contextual bookmark toolbar will pop up.

The Bookmarks feature is production-ready but does not include integration with the linking experience yet (see #17230).

Integrators should guide their users on linking to bookmarks using the # anchors.

PUBLISHING AGREEMENT

Introduction

This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”.

Grant of Rights

The Author grants the Publisher full right and title to the following, in perpetuity:

  • To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future.
  • To create or devise modified, abridged, or derivative works based on the works listed.
  • To allow others to use the listed works at their discretion, without providing additional compensation to the Author.

The Author grants these rights on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future.

Any rights not granted to the Publisher above remain with the Author.

The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature.

This demo presents a limited set of features. Visit the feature-rich editor example to see more in action.

# Handling the anchor markup

Do not worry about setting a bookmark inside an empty paragraph. The block with the a tag will not be rendered in the final content (for example for printing).

The feature converts anchors into bookmarks during the initialization of the editor or while replacing the editor data with setData(). The notation based on the id attribute in an a HTML element without a href attribute is converted. Similar notations meet the conditions, too:

  • an a HTML element with a name attribute,
  • an a HTML element with the same name and id attributes,
  • an a HTML element with different name and id attributes.

By default, all bookmarks created in the editor only have the id="..." attribute in the editor data.

# Installation

⚠️ New import paths

Starting with version 42.0.0, we changed the format of import paths. This guide uses the new, shorter format. Refer to the Packages in the legacy setup guide if you use an older version of CKEditor 5.

After installing the editor, add the feature to your plugin list and toolbar configuration:

import { ClassicEditor, Bookmark } from 'ckeditor5';

ClassicEditor
	.create( document.querySelector( '#editor' ), {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Bookmark, /* ... */ ],
		toolbar: [ 'bookmark', /* ... */ ]
	} )
	.then( /* ... */ )
	.catch( /* ... */ );

# Configuration

By default, the conversion of wrapped anchors is turned on. It allows to convert non-empty anchor elements into bookmarks. For example:

<a id="foo">Foo bar baz</a>

will be converted into a bookmark and the output will look like on the example below:

<a id="foo"></a>Foo bar baz

You can disable the automatic conversion by setting the config.bookmark.enableNonEmptyAnchorConversion to false in the editor configuration.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        bookmark: {
            enableNonEmptyAnchorConversion: false
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Bookmarks on blocks

At this time, if a bookmark is attached to a block, it appears before it. However, we plan to expand this solution in the future. We invite you to help us gather feedback for linking directly to blocks and auto generating IDs.

Here are some other CKEditor 5 features that you can use similarly to the bookmark plugin to cross-link and structure your text better:

  • The link feature allows adding local and global URLs to the content.
  • The document outline displays the list of sections (headings) of the document next to the editor.
  • The table of contents lets you insert a widget with a list of headings (section titles) that reflects the structure of the document.

# Common API

The Bookmark plugin registers the 'bookmark' UI button component implemented by the bookmark UI feature, and the following commands:

We recommend using the official CKEditor 5 inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

# Contribute

The source code of the feature is available on GitHub at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark.