ENML
Understanding the Evernote Markup Language
Overview
ENML is the markup language used by Evernote to represent the content of notes. Because ENML is a superset of XHTML, it's easy to present rich content in Evernote notes.
Introduction
ENML was designed to provide a secure and portable document representation that could be consistently rendered on various clients and platforms. It's largely based on a subset of XHTML. The current version of ENML, version 2, is intentionally broadened to reject less real-world HTML to reduce the likelihood of synchronization failures. This means that all attributes are defined as CDATA instead of more restrictive types, and every HTML element may embed every other HTML element.
ENML is formally defined in http://xml.evernote.com/pub/enml2.dtd. The content of each note within the Evernote service must strictly comply with this ENML DTD. The service will validate a note's content against this DTD before accepting any call to NoteStore.createNote or NoteStore.updateNote.
Because ENML is based on XHTML and must strictly comply with the ENML DTD, there are a couple of things you should keep in mind. Every tag must be closed and properly balanced, so instead of using <hr>, you must use <hr/>. Tag names must be all lowercase.
Note: While it is possible to rely on the Evernote Cloud API to validate the ENML of your notes, we recommend downloading the DTD file (linked above) and use it to validate your note's XML within your app. A few reasons this is a good idea:
- Note validation will be much faster when performed locally.
- Note validation can be performed offline.
- The results of validating your notes locally will be the same as if you were to rely on the Evernote Cloud API to validate your ENML.
Added elements
ENML adds four Evernote-specific elements to XHTML:
en-note
en-note is the top-level element for all ENML documents. It replaces the HTML and BODY tags from an XHTML document. en-note supports the following optional attributes:
- bgcolor - background color of the note
- text - text color
- style, title, lang, xml:lang, dir - optional attributes with the same semantics as the corresponding XHTML standard attributes.
In its simplest form, an en-note element would look something like this:
en-media
en-media is used to mark the location where one of a note's resources should be embedded within the document. For example, this would be used instead of an HTML <img> element to mark the location where an image resource should be displayed within the note when it is displayed. en-media supports the following attributes:
- hash - MD5 checksum of the Resource body, in hexidecimal format. This is the primary unique identifier of the Resource. Please note that this refers to the MD5 hash of the file itself (the binary file stream) and not the hash of the base64 string encoding of the file or the hash of the GUID. (required)
- type - the MIME type of the Resource. (required)
- align, alt, longdesc, height, width, border, hspace, vspace, usemap - optional attributes with the same semantics as the corresponding 'img' attributes. These should be used to help format the Resource when it is displayed.
- style, title, lang, xml:lang, dir - optional attributes with the same semantics as the corresponding XHTML standard attributes.
en-crypt
en-crypt contains encrypted and Base-64 encoded text which can be displayed in a full desktop client after the user has entered the appropriate decryption passphrase. The Base-64 encoded ciphertext is contained within the CDATA body of the element. en-crypt supports the following optional attributes:
- hint - the passphrase hint to present to the user during decryption.
- cipher - the name of the symmetric cipher that was used to encrypt the text. E.g. "RC2"
- length - the length of the symmetric cipher key, in bits. E.g. 64
en-todo
en-todo marks the location of a "To Do" checkbox within a note's content. en-todo does not encompass any specific text; it is a self-closing tag that can include a single attribute:
- checked - "true" if the To Do item has been completed, or "false" if the item has not been completed. If absent, this defaults to "false".
Permitted elements
ENML permits the use of the following standard XHTML elements:
- a
- abbr
- acronym
- address
- area
- b
- bdo
- big
- blockquote
- br
- caption
- center
- cite
- code
- col
- colgroup
- dd
- del
- dfn
- div
- dl
- dt
- em
- font
- h1
- h2
- h3
- h4
- h5
- h6
- hr
- i
- img
- ins
- kbd
- li
- map
- ol
- p
- pre
- q
- s
- samp
- small
- span
- strike
- strong
- sub
- sup
- table
- tbody
- td
- tfoot
- th
- thead
- title
- tr
- tt
- u
- ul
- var
- xmp
Prohibited elements
ENML is designed to allow the representation of static documents. As such, "active" elements of XHTML such as forms and scripts are not allowed within ENML. The following XHTML elements are disallowed; attempting to create a note containing these elements will result in the Evernote Cloud API returning EDAMUserException with the error code EDAMErrorCode.ENML_VALIDATION (indicating malformed or invalid ENML):
- applet
- base
- basefont
- bgsound
- blink
- body
- button
- dir
- embed
- fieldset
- form
- frame
- frameset
- head
- html
- iframe
- ilayer
- input
- isindex
- label
- layer,
- legend
- link
- marquee
- menu
- meta
- noframes
- noscript
- object
- optgroup
- option
- param
- plaintext
- script
- select
- style
- textarea
- xml
A number of attributes are also disallowed from the supported XHTML elements:
- id
- class
- onclick
- ondblclick
- on*
- accesskey
- data
- dynsrc
- tabindex
URLs using script or data protocols are disallowed and will be rejected by the service.
Styling note content
ENML allows the use of CSS to style notes. All styles must be specified in-line using the 'style' attribute. References to external or embedded stylesheets and the use of the 'class' attribute are not allowed.
ENML does not define or enforce a set of supported styles. Most Evernote client applications display note content within embedded browser controls (e.g. WebView) and thus support almost all standard CSS properties. However, because notes can be viewed in both desktop and mobile apps, note authors should use caution when styling notes. Always see what your note looks like on various platforms when designing your note's content.
Representing plaintext notes
Applications that wish to store plaintext notes in Evernote must convert newlines into HTML-style blocks. To ensure that notes render correctly across clients, we recommend that you wrap each paragraph in a <div> element. For each blank line, insert a <div> containing a single <br>. For example, the following plaintext:
would be represented in ENML as follows:
Before submitting HTML content over the EDAM API the client application is expected to follow the following steps:
1. Convert the document into valid XML
2. Discard all tags that are not accepted by the ENML DTD
3. Convert tags to the proper ENML equivalent (e.g. BODY becomes EN-NOTE)
4. Validate against the ENML DTD
5. Validate href and src values to be valid URLs and protocols