Source editing

The source editing feature lets you view and edit the source of your document.

# Demo

Use the editor below to see the source editing plugin in action. Toggle the source editing mode and make some changes in the HTML code (for example, add a new paragraph or an ordered list). Then leave the source editing mode and see that the changes are present in the document content.

You can also use one of the many CKEditor 5 features available in the toolbar and check how they render in the HTML source. Notice the collapsible table of contents, available thanks to the general HTML support feature. The feature introduces HTML elements not yet covered by the official plugins.

Table of contents

1. The singing Canadian
2. Spaceflights
3. Bibliography
4. Space Oddity

The singing Canadian

Chris Austin Hadfield was born on August 29, 1959, in Canada. As a child, he watched the Apollo 11 moon landing, and it inspired him to become an astronaut. At the time, Canada had no space program, so Hadfield joined the Royal Canadian Air Forces and served as a fighter pilot for 25 years.

In 1992, Hadfield was accepted into the Canadian astronaut program by the Canadian Space Agency. He flew his first mission to the Russian Mir space station in 1995 aboard the Atlantis space shuttle. Six years later onboard the Endeavour space shuttle he flew to the International Space Station. He revisited the ISS in 2012 flying a Russian Soyuz spacecraft and taking command over the station during Expedition 34/35.

Hadfield was most recognized by the general public for his rendition of the famous Space Oddity song by David Bowie which he recorded onboard the International Space Station. He also recorded numerous educational materials for schools while working in orbit. After his retirement from the astronaut service, he wrote three books based on his experience.

Spaceflights

Hadfield has flown to space thrice. He has also performed two EVAs (extra-vehicular activity, a spacewalk) that lasted together for 14 hours 53 minutes and 38 seconds.

Flight	Date	Spacecraft	Function	Emblem
STS-74	12-20.11.1995	Atlantis	Mission Specialist
STS-100	19.04.2001-01.05.2001	Endeavour	Mission Specialist
Expedition 34/35	19.12.2012-14.05.2013	Soyuz TMA-07M	ISS Commander

Bibliography

• An Astronaut's Guide to Life on Earth: What Going to Space Taught Me About Ingenuity, Determination, and Being Prepared for Anything. Little, Brown and Company, 2013
• You Are Here: Around the World in 92 Minutes: Photographs from the International Space Station. Little, Brown and Company, 2014
• The Darkest Dark. Illustrated by Terry and Eric Fan. Little, Brown and Company, 2016
• The Apollo Murders Random House, 2021

Space Oddity

The rendition of Space Oddity by Chris Hadfield, shot in 2013 was the first-ever music video shot in space.

The only reason Chris Hadfield isn't the coolest guy on Earth is that he's not on Earth.

A comment by August Vctjuh on YouTube.

# Installation

To add this feature to your rich-text editor, install the @ckeditor/ckeditor5-source-editing package:

npm install --save @ckeditor/ckeditor5-source-editing

And add it to your plugin list configuration:

import { SourceEditing } from '@ckeditor/ckeditor5-source-editing';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SourceEditing, /* ... */ ],
        toolbar: [ 'sourceEditing', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

To utilize the Markdown source editing mode just add the Markdown output plugin to the editor.

import { SourceEditing } from '@ckeditor/ckeditor5-source-editing';
import { Markdown } from '@ckeditor/ckeditor5-markdown-gfm';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SourceEditing, Markdown, /* ... */ ],
        toolbar: [ 'sourceEditing', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Limitations and incompatibilities

# Real-time collaboration

Source editing used during real-time collaboration brings a severe risk of data loss in a way that may be difficult for a user to notice and understand.

After you switch to source editing, incoming changes performed by remote users are not reflected in the source code. When you switch back (saving the source code), all changes done in the meantime by other users will be overwritten.

Due to this risk, these features are not allowed to be used together by default. When both are added to the editor, it will throw an error. You have to explicitly enable source editing mode for real-time collaboration, acknowledging this risk.

To enable the features, set the sourceEditing.allowCollaborationFeatures configuration flag to true.

# Comments and track changes

The comments and track changes features use markers to mark affected parts of the document.

In the source editing mode, it is possible for a user to modify these markers’ boundaries. The user can change the range of a comment or tracked change, or remove them. This presents a potential problem related to users permissions.

The editor will show a warning in the browser’s console when these plugins and source editing plugin are used together.

To turn off the warning, set the sourceEditing.allowCollaborationFeatures configuration flag to true.

# Support for various HTML elements

The editor will save changes made to the document data source only if it “understands” them. It means only when one of the loaded plugins recognizes the given syntax (HTML or Markdown). All syntax unsupported by the editor will be filtered out.

For example, if the editor does not have the horizontal line plugin loaded, the <hr> tag added in the document source will be removed upon exit from the source editing mode.

To avoid that, make sure that your editor configuration has all the necessary plugins that handle various HTML tags.

In many cases, to enable advanced modifications through the source editing, you might need to enable the HTML embed feature and the General HTML support feature, or write a plugin that will enable a given HTML tag or attribute support.

# HTML normalization

When the editor reads the source data, it converts the data to a normalized, high-level abstract data model structure, on which it operates. This structure differs from the HTML or Markdown code.

Note, that the same document “state” may be described using HTML in various ways.

For example, <strong><em>Foo</em></strong> and <i><b>Foo</b></i> both produce the “Foo” text with bold and italic styling. Both will be represented the same when loaded to the internal editor data model.

When the editor data model is later converted back to the document source data, it will be normalized regardless of what the original input was. In effect, <i><b>Foo</b></i> will eventually become <strong><em>Foo</em></strong>.

This limitation is a direct consequence of the core editor architecture and cannot be worked around. Although it is possible to change the editor final output, the input data will always be normalized to that output format.

# Impact on the editor UI

Editor features rely on high-level editor API which cannot be used when the source editing is active. Due to that, when you switch to the source editing mode, all toolbar buttons become disabled and all dialog windows are closed.

# Revision history

Saving the modified document source is internally executed through replacing the old data with the new one. As a consequence, it will be represented in revision history as a total replace change (insertion + deletion).

The editor will show a warning in the browser’s console when revision history and source editing are loaded together.

To turn the warning off, set the sourceEditing.allowCollaborationFeatures configuration flag to true.

# Restricted editing

Restricted editing is not enforced in the source editing mode. The user will be able to edit any part of the document, as well as remove the markers that mark the boundaries of restricted areas.

The editor will show a warning in the browser’s console when restricted editing and source editing are loaded together.

# Markdown source view

The source editing plugin also works well with the Markdown output plugin. You do not need any special configuration: just add the plugin to the editor, and the source editing mode will display Markdown instead of HTML.

p {
    text-align: center;
    color: red;
}

# Related features

There are other source-related CKEditor 5 features you may want to check:

• General HTML support – Allows you to enable HTML features (elements, attributes, classes, styles) that are not supported by other dedicated CKEditor 5 plugins.
• Full page HTML – Allows using CKEditor 5 to edit entire HTML pages, from <html> to </html>, including the page metadata.
• HTML embed – Allows embedding an arbitrary HTML snippet in the editor.
• Markdown output – Allows for Markdown output instead of HTML output.

# Common API

The SourceEditing plugin registers:

• The 'sourceEditing' UI button component.

# Contribute

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