Skip to content

Commit 21c6f46

Browse files
arkflpcarkflpc
authored
Merge pull request #17278 from ckeditor/ck/epic/1944-bookmark
Feature (bookmark): Introduces the Bookmarks feature. Closes #1944. Fix (list): Inserting or dropping a paragraph after the end of a list should not convert the paragraph to a list item. Closes #17224.
2 parents 9decc1e + ea228d5 commit 21c6f46

File tree

98 files changed

+11603
-73
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

98 files changed

+11603
-73
lines changed

‎docs/_snippets/build-classic-source.js

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@
66
/* globals window */
77

88
import { AutoImage, ImageInsert } from '@ckeditor/ckeditor5-image';
9+
import { Bookmark } from '@ckeditor/ckeditor5-bookmark';
910
import ClassicEditor from './build-classic.js';
1011

1112
window.ClassicEditor = ClassicEditor;
1213

1314
ClassicEditor.builtinPlugins.push( ImageInsert );
1415
ClassicEditor.builtinPlugins.push( AutoImage );
16+
ClassicEditor.builtinPlugins.push( Bookmark );

‎docs/_snippets/examples/classic-editor.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ClassicEditor
1515
'undo', 'redo',
1616
'|', 'heading',
1717
'|', 'bold', 'italic',
18-
'|', 'link', 'insertImage', 'insertTable', 'mediaEmbed',
18+
'|', 'link', 'bookmark', 'insertImage', 'insertTable', 'mediaEmbed',
1919
'|', 'bulletedList', 'numberedList', 'outdent', 'indent'
2020
]
2121
},

‎packages/ckeditor5-bookmark/CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Changelog
2+
=========
3+
4+
All changes in the package are documented in https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md.

‎packages/ckeditor5-bookmark/LICENSE.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Software License Agreement
2+
==========================
3+
4+
**CKEditor&nbsp;5 bookmark feature** – https://github.com/ckeditor/packages/ckeditor5-bookmarks <br>
5+
Copyright (c) 2003–2024, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
6+
7+
Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
8+
9+
Sources of Intellectual Property Included in CKEditor
10+
-----------------------------------------------------
11+
12+
Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
13+
14+
Trademarks
15+
----------
16+
17+
**CKEditor** is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com) All other brand and product names are trademarks, registered trademarks, or service marks of their respective holders.

‎packages/ckeditor5-bookmark/README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
CKEditor&nbsp;5 bookmark feature
2+
================================
3+
4+
[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-bookmark.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)
5+
[![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
6+
[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
7+
8+
This package contains the bookmark feature for CKEditor&nbsp;5. It allows to add and manage the bookmarks attached to the content of editor for fast access and more efficient content creation.
9+
10+
## Demo
11+
12+
Check out the [demo in the bookmark feature](https://ckeditor.com/docs/ckeditor5/latest/features/bookmarks.html#demo) guide.
13+
14+
## Documentation
15+
16+
See the [`@ckeditor/ckeditor5-bookmark` package](https://ckeditor.com/docs/ckeditor5/latest/api/bookmark.html) page in [CKEditor&nbsp;5 documentation](https://ckeditor.com/docs/ckeditor5/latest/) as well as the [bookmark](https://ckeditor.com/docs/ckeditor5/latest/features/bookmarks.html) feature guide.
17+
18+
## Installation
19+
20+
```bash
21+
npm install ckeditor5
22+
```
23+
24+
## License
25+
26+
Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

‎packages/ckeditor5-bookmark/ckeditor5-metadata.json

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"plugins": [
3+
{
4+
"name": "Bookmark",
5+
"className": "Bookmark",
6+
"description": "Allows to insert a bookmark into the content to provide fast access to important sections.",
7+
"docs": "features/bookmarks.html",
8+
"path": "src/bookmark.js",
9+
"uiComponents": [
10+
{
11+
"type": "Button",
12+
"name": "bookmark",
13+
"iconPath": "@ckeditor/ckeditor5-core/theme/icons/bookmark.svg"
14+
}
15+
],
16+
"htmlOutput": [
17+
{
18+
"elements": "a",
19+
"attributes": "id"
20+
}
21+
]
22+
}
23+
]
24+
}

‎packages/ckeditor5-bookmark/docs/_snippets/features/bookmark.html

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
2+
<div class="ck ck-content" id="snippet-bookmark">
3+
<h2>
4+
PUBLISHING AGREEMENT
5+
</h2>
6+
<h3>
7+
Introduction
8+
</h3>
9+
<p>
10+
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”.
11+
</p>
12+
<h3>
13+
<a id="Rights"></a>Grant of Rights
14+
</h3>
15+
<p>
16+
The Author grants the Publisher full right and title to the following, in perpetuity:
17+
</p>
18+
<ul>
19+
<li>
20+
To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future.
21+
</li>
22+
<li>
23+
To create or devise modified, abridged, or derivative works based on the works listed.
24+
</li>
25+
<li>
26+
To allow others to use the listed works at their discretion, without providing additional compensation to the Author.
27+
</li>
28+
</ul>
29+
<p>
30+
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.
31+
</p>
32+
<p>
33+
Any rights not granted to the Publisher above remain with the Author.
34+
</p>
35+
<p>
36+
The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature.
37+
</p>
38+
</div>

‎packages/ckeditor5-bookmark/docs/_snippets/features/bookmark.js

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
/**
2+
* @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
3+
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4+
*/
5+
6+
/* globals console, window, document */
7+
8+
// source editing only added for testing purposes, remove when done
9+
10+
import { CKBox, CKBoxImageEdit } from '@ckeditor/ckeditor5-ckbox';
11+
import { PictureEditing, ImageInsert, ImageResize, AutoImage } from '@ckeditor/ckeditor5-image';
12+
import { LinkImage } from '@ckeditor/ckeditor5-link';
13+
import { Bookmark } from '@ckeditor/ckeditor5-bookmark';
14+
import { SourceEditing } from '@ckeditor/ckeditor5-source-editing';
15+
import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config.js';
16+
import { TOKEN_URL } from '@ckeditor/ckeditor5-ckbox/tests/_utils/ckbox-config.js';
17+
18+
// Umberto combines all `packages/*/docs` into the `docs/` directory. The import path must be valid after merging all directories.
19+
import ClassicEditor from '../build-classic.js';
20+
21+
ClassicEditor.builtinPlugins.push( Bookmark, PictureEditing, ImageInsert, SourceEditing,
22+
ImageResize, AutoImage, LinkImage, CKBox, CKBoxImageEdit );
23+
24+
ClassicEditor
25+
.create( document.querySelector( '#snippet-bookmark' ), {
26+
toolbar: {
27+
items: [
28+
'bookmark',
29+
'|', 'undo', 'redo', '|', 'heading',
30+
'|', 'bold', 'italic',
31+
'link', 'insertImage', 'insertTable', 'blockQuote', 'mediaEmbed',
32+
'|', 'bulletedList', 'numberedList', 'outdent', 'indent', 'sourceEditing'
33+
]
34+
},
35+
menuBar: {
36+
isVisible: true
37+
},
38+
image: {
39+
toolbar: [
40+
'imageStyle:inline', 'imageStyle:block', 'imageStyle:wrapText', '|',
41+
'toggleImageCaption', 'imageTextAlternative', 'ckboxImageEdit'
42+
]
43+
},
44+
ui: {
45+
viewportOffset: {
46+
top: window.getViewportTopOffsetConfig()
47+
}
48+
},
49+
ckbox: {
50+
tokenUrl: TOKEN_URL,
51+
allowExternalImagesEditing: [ /^data:/, 'origin', /ckbox/ ],
52+
forceDemoLabel: true
53+
},
54+
cloudServices: CS_CONFIG
55+
} )
56+
.then( editor => {
57+
window.editorBasic = editor;
58+
window.attachTourBalloon( {
59+
target: window.findToolbarItem( editor.ui.view.toolbar, item => item.label && item.label === 'Bookmark' ),
60+
text: 'Click to insert a bookmark.',
61+
editor,
62+
tippyOptions: {
63+
placement: 'bottom-start'
64+
}
65+
} );
66+
} )
67+
.catch( err => {
68+
console.error( err );
69+
} );

‎packages/ckeditor5-bookmark/docs/api/bookmark.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
category: api-reference
3+
---
4+
5+
# CKEditor&nbsp;5 bookmark feature
6+
7+
[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-block-quote.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)
8+
9+
This package implements bookmark support for CKEditor&nbsp;5.
10+
11+
## Demo
12+
13+
Check out the {@link features/bookmarks#demo demo in the bookmarks feature guide}.
14+
15+
## Documentation
16+
17+
See the {@link features/bookmarks bookmarks feature guide} and the {@link module:block-quote/blockquote~BlockQuote} plugin documentation.
18+
19+
## Installation
20+
21+
This package is part of our open-source aggregate package.
22+
23+
```bash
24+
npm install ckeditor5
25+
```
26+
27+
## Contribute
28+
29+
The source code of this package is available on GitHub in [https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark).
30+
31+
## External links
32+
33+
* [`@ckeditor/ckeditor5-bookmark` on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)
34+
* [`ckeditor/ckeditor5-bookmark` on GitHub](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark)
35+
* [Issue tracker](https://github.com/ckeditor/ckeditor5/issues)
36+
* [Changelog](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md)

‎packages/ckeditor5-bookmark/docs/features/bookmarks.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
category: features
3+
menu-title: Bookmarks
4+
meta-title: Bookmarks | CKEditor 5 Documentation
5+
meta-description: The bookmarks feature allows for adding and managing bookmark anchors attached to the content.
6+
modified_at: 2024-10-21
7+
---
8+
9+
# Bookmarks
10+
11+
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.
12+
13+
## Demo
14+
15+
Use the bookmark toolbar button {@icon @ckeditor/ckeditor5-core/theme/icons/bookmark.svg 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`).
16+
17+
To use the bookmark as an anchor in the content, add a link {@icon @ckeditor/ckeditor5-link/theme/icons/link.svg Add link} and put the bookmark name as target. In this example 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.
18+
19+
{@snippet features/bookmark}
20+
21+
<info-box info>
22+
This demo presents a limited set of features. Visit the {@link examples/builds/full-featured-editor feature-rich editor example} to see more in action.
23+
</info-box>
24+
25+
## Handling the anchor markup
26+
27+
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).
28+
29+
The feature converts anchors into bookmarks during the {@link getting-started/setup/getting-and-setting-data#initializing-the-editor-with-data initialization of the editor} or while {@link getting-started/setup/getting-and-setting-data#replacing-the-editor-data-with-setdata 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:
30+
* an `a` HTML element with a `name` attribute,
31+
* an `a` HTML element with the same `name` and `id` attributes,
32+
* an `a` HTML element with different `name` and `id` attributes.
33+
34+
By default, all bookmarks created in the editor only have the `id="..."` attribute in the {@link getting-started/setup/getting-and-setting-data#getting-the-editor-data-with-getdata editor data}.
35+
36+
## Installation
37+
38+
<info-box info>
39+
⚠️ **New import paths**
40+
41+
Starting with {@link updating/update-to-42 version 42.0.0}, we changed the format of import paths. This guide uses the new, shorter format. Refer to the {@link getting-started/legacy-getting-started/legacy-imports Packages in the legacy setup} guide if you use an older version of CKEditor&nbsp;5.
42+
</info-box>
43+
44+
After {@link getting-started/quick-start installing the editor}, add the feature to your plugin list and toolbar configuration:
45+
46+
```js
47+
import { ClassicEditor, Bookmark } from 'ckeditor5';
48+
49+
ClassicEditor
50+
.create( document.querySelector( '#editor' ), {
51+
plugins: [ Bookmark, /* ... */ ],
52+
toolbar: [ 'bookmark', /* ... */ ]
53+
} )
54+
.then( /* ... */ )
55+
.catch( /* ... */ );
56+
```
57+
58+
## Configuration
59+
60+
By default, the conversion of wrapped anchors is turned on. It allows to convert non-empty anchor elements into bookmarks. For example:
61+
62+
```html
63+
<a id="foo">Foo bar baz</a>
64+
```
65+
66+
will be converted into a bookmark and the output will look like on the example below:
67+
68+
```html
69+
<a id="foo"></a>Foo bar baz
70+
```
71+
72+
You can disable the automatic conversion by setting the {@link module:bookmark/bookmarkconfig~BookmarkConfig#enableNonEmptyAnchorConversion `config.bookmark.enableNonEmptyAnchorConversion`} to `false` in the editor configuration.
73+
74+
```js
75+
ClassicEditor
76+
.create( document.querySelector( '#editor' ), {
77+
plugins: [ Bookmark, /* ... */ ],
78+
toolbar: [ 'bookmark', /* ... */ ],
79+
bookmark: {
80+
enableNonEmptyAnchorConversion: false
81+
}
82+
} )
83+
.then( /* ... */ )
84+
.catch( /* ... */ );
85+
```
86+
## Bookmarks on blocks
87+
88+
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](https://github.com/ckeditor/ckeditor5/issues/17264).
89+
90+
## Related features
91+
92+
Here are some other CKEditor&nbsp;5 features that you can use similarly to the bookmark plugin to cross-link and structure your text better:
93+
94+
* The {@link features/link link feature} allows adding local and global URLs to the content.
95+
* The {@link features/document-outline document outline} displays the list of sections (headings) of the document next to the editor.
96+
* The {@link features/document-outline table of contents} lets you insert a widget with a list of headings (section titles) that reflects the structure of the document.
97+
98+
## Common API
99+
100+
The {@link module:bookmark/bookmark~Bookmark} plugin registers the `'bookmark'` UI button component implemented by the {@link module:bookmark/bookmarkui~BookmarkUI bookmark UI feature}, and the following commands:
101+
* the `'insertBookmark'` command implemented by the {@link module:bookmark/insertbookmarkcommand~InsertBookmarkCommand editing feature}.
102+
* the `'updateBookmark'` command implemented by the {@link module:bookmark/updatebookmarkcommand~UpdateBookmarkCommand editing feature}.
103+
104+
<info-box>
105+
We recommend using the official {@link framework/development-tools/inspector CKEditor&nbsp;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.
106+
</info-box>
107+
108+
## Contribute
109+
110+
The source code of the feature is available on GitHub at [https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark).

‎packages/ckeditor5-bookmark/lang/contexts.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"Bookmark": "The label of the bookmark toolbar button. Also, a bookmark form header.",
3+
"Insert": "The button in the bookmark insert form.",
4+
"Update": "The button in the bookmark update form.",
5+
"Edit bookmark": "Button opening the Bookmark editing balloon.",
6+
"Remove bookmark": "Toolbar button tooltip for bookmark remove button.",
7+
"Bookmark name": "The label of the input in the bookmark insert and update form. Also, the tooltip for the bookmark name in the bookmark preview.",
8+
"Enter the bookmark name without spaces.": "The description of bookmark input in the bookmark insert form.",
9+
"Bookmark must not be empty.": "The error message. Displayed when the bookmark name is empty.",
10+
"Bookmark name cannot contain space characters.": "The error message. Displayed when provided name includes spaces.",
11+
"Bookmark name already exists.": "The error message. Displayed when provided name already exists.",
12+
"bookmark widget": "The label for the bookmark widget."
13+
}

0 commit comments

Comments
 (0)