fileformat.txt

-------------------------------------
KEYNOTE NF -  File Format Specification 3.1  (KeyNote NF 2.0.0+)
Last updated: 30 Nov 2024

<dprado.keynote@gmail.com>

* From version 1.7.7, certain metainformation is encoded in UTF-8 without BOM, not in ASCII.
 They are the corresponding to the following keys:
 NN, ND, VN, RV, VF, NA, EN

* Since version 1.9.2 there is a change of terminology: 
 Simple notes / Tree Notes + nodes   ->   "Folders" with "notes"
 Tabs are now called "Folders" containing one or more "Notes"
 "Simple notes" disappear. When opening files with "simple notes", they are converted to "Tree-Notes" (now "Folders") with a single node initially, 
 and the tree panel hidden

* KeyNote will continue loading .knt files created with older versions. See "fileformat_2.1 (until v1.9.5).txt"
* The format described here corresponds to how files are saved since version 2.0.0 of the application

-------------------------------------

KeyNote uses plain text files which can be read on a line-by-line basis.
RTF data is stored as-is, without any conversion.

The file consists of a header section and a data section.

The header identifies the file as a valid KeyNote file and stores some metainformation about the file, such as the date and time the file was created, which folder was last active, user-defined  description and comment, etc.

The data section consists of subsections for list of notes (with their entries) and list of folder (with their nodes). Sections and subsections are separated by special markers, described below. Optionally can appear sections for bookmarks and images.

Almost all elements in the data section, where the properties of folder, notes and nodes are stored, are optional. KeyNote fills in any missing data using default values. This applies even to names of notes. Default values are configured by user via Tools|Default settings. There is a bug, however, which prevents KeyNote from automatically assigning default names for tree nodes, so if a particular tree node has no name specified in the file its caption will be blank. Other than that, you can leave out all elements of a file. Only the markers are required, because they define the structure of the file.

For tree nodes, the level number must also be specified, because it is required to re-create the tree hierarchy: level value indicates nesting, where level value of zero means top-level (root) node. If no level is specified for a node, it is assumed to be at the same level as the previously read node.

Some elements or identifiers mentioned in this document may not appear in every KeyNote file. This is because some elements are only stored in the file if necessary. For instance, the file header carries information about the folder which was used for clipboard capture. If clipboard capture was not enabled at the time the file was saved, this property is not stored in the header.

(As an example of the elements and properties shown in this document a sample file "fileformat_3.0.knt" is included. The file contains two folders with several notes. Most of then contains RTF and one plain text. There is also a virtual node and a linked node. An example of use of internal hyperlink, bookmarks and a little embedded image is added
)

This document does not describe the structure of encrypted files, because this is closely tied to the encryption library used (DCPCrypt 1.0, by David Barton). Please see KeyNote source code to see how encrypted files are created and handled.


-------------------------------------

HEADER SECTION:

Each line begins with '#', followed by a single character that identifies a header field. All header fields except for the first line are optional and will be auto-created if missing (KeyNote will use default values). The first line identifies the file as a valid KeyNote file and MUST be present. Lines not understood are simply ignored, as long as each line begins with the '#' character.


Header ID - required; must not be changed
#!GFKNT 3.0

Comment line, ignored
# This is an automatically generated file. Do not edit.

Optional: user-defined file description (single-line)
#/This is the optional description

Optional: user-defined comment (single-line)
#?This is the optional comment

Optional: Number of "active" folder (zero-based)
#$0

Optional: Date and time the file was created
#C21-05-2003 15:24:50

Optional: "Flags" string - see "FILE FLAGS", below.
#^010000000000000000000000

Optional: icon file to use for tray icon
#Tc:\delphi\projects\keynote\img\alticon.ico

Optional: external file where tab icons are stored
#Fc:\delphi\projects\keynote\alticons.icn

Optional: if clipboard capture was active at the time the file was saved, this is the index of the folder which was used for clipboard capture
#L0


--------------------------------

NOTES, ENTRIES AND NODES

Just after Header section, the file includes the data of all the notes, independent of the folders.
The first line indicates the number of notes:

N:= <Number notes in File>

Each note is described with all its metadata, and with its entries. 
The RTF or TXT data belongs to an entry. In version 2.0.0 only one entry is used for each note, but
in next versions will be used any number of entries.

Notes are identified with a GID (Global Identifier).
Folders group notes and provide them as "nodes" with a hierarchical structure. Any note can be located in any
number of folders, and in any folder can be several nodes linked to the same note.

Nodes in Folders, also identified with a GID, are ordered according to their hierarchical structure; 
include also information specific to the tree nodes, like color or checked state.

Similarly to the list of Notes, before describing all its nodes, each folder add a line that indicates
the number of nodes in the folder:

n:= <Number nodes in Folder>


--------------------------------

SECTION (START AND END) MARKERS:

The start of each subsection is marked by a single line. The first character in such lines is always the percent sign. For example, '%+' marks the start of a (tree-type) folder. Markers are as follows:

%*
marks start of NOTE

%.
marks start of an ENTRY in a Note

%:
marks start of RTF data. Please see below for notes about the RTF/PLAIN TEXT data section.

%>
marks start of PLAIN TEXT data. Please see below for notes about the RTF/PLAIN TEXT data section.



%+
marks start of a FOLDER (tree-type folder)

%-
marks start of Note NODE


%BK 
marks start of BOOKMARKS SECTION (auxiliary bookmarks created with Search|Set Bookmark)


IMAGE SECTIONS (%S, %I, %EI)
  From version 1.8.1, in the case of using a image storage mode other than Embedded RTF, the application will use an EXTENDED KNT FORMAT when saving in
  which new blocks have been incorporated at the end of the file, to allow including the registration of stores and images
  It is describe below (IMAGE SECTIONS)

%S
marks start of Storage section

%I
marks start of Image section

%EI
marks start of Embedded Images		  




%%
marks end of file (KeyNote stops reading the file here, but it will also stop at end of file, so this marker is not required, though always present in files generated by KeyNote.)

  Really this mark is not optional, at least until version 1.7.9, because tree nodes read will not be be added until it is found a mark of new tree node, new tab or mark of end of file.
  So, if the file doesn't include the "%%" mark and ends with a tree node, that last tree node will be lost. This problem doesnt occur with standard rtf tabs.

No other markers are used. No end-of-section markers are used, except for end-of-file, above.

 

--------------------------------
DATA SECTION:


Each line begins with a 2-character identifier, possibly followed by equal sign (=) and data. For example,
	NN=title
identifies the folder name.

Each line is guaranteed to be at least one character long. Each line with an identifier is guaranteed to be at least three characters long: the two characters of the identifier itself, plus the equal sign. (The file can be analyzed a little faster if we don't have to check for zero-length strings.)

* Note: 2-character identifiers are case sensitive  (Ns <> NS <> ns)


List of NOTES (with their ENTRIES)
======================================

Number of notes in file
N:=12

New NOTE starts =====================
%*

Note name
ND=This is the name of a note

Unique note ID within the .knt file  (Global ID)  (New in 1.9.3)
GI=1

Optional: Note alias
AL=This is an alternative name, or alias, of the note

Optional: ID of selected Entry in the note (zero-based) (if ID of selected Entry <> 0)
SE=0

Optional: Caret position (zero-based) in selected entry in the note
SS=60

Optional: Last modification date  (yymmddhhmi)
LM=2511242205
 Corresponds to: 25 nov 2024 22:05

Note state
It is only necessary if <> 0
Is the hexadecimal representation of the options available in each Note, as described below ("NOTE STATE")
Ns=02

Optional: relative path to file, if node is a virtual node
RV=toDo.txt

Optional: full absolute path to file, if node is a virtual node (see also node flags)
VF=c:\delphi\projects\keynote\doc\toDo.txt


New Note ENTRY in Note starts -----------
%.

ID of Entry in the note (zero-based). (Only necessary if id<> 0)
id=1

Date and time the entry was created
DC=21-05-2003 15:25:25

Entry state (Only necessary if NS<>0)
NS=0002

RTF data follows:
%:
{\rtf1\ansi\deff0{\fonttbl{\f0\fnil\fcharset238{\*\fname Courier New;}Courier New CE;}{\f1\fnil\fcharset0 Courier New;}}
{\*\generator Riched20 5.40.11.2210;}\viewkind4\uc1\pard\lang1045\f0\fs24 This is the text of the node.\par
This is another line of text.\par
\lang1033\f1\par
}

Plain text data follows:
%>
;A line in the Plain text note
;Another line in the Plain text note



List of FOLDERS, with their Note NODES (NNodes)
========================================

New Folder starts ============================
(All folders are now "tree" folder)
%+

Folder name
NN=Simple folder

Unique folder ID (integer, auto-created if missing)
ID=2

Folder icon index (index for the icon displayed on the folder's tab)
II=7

Date and time the folder was created
DC=21-05-2003 15:25:25

Index of the folder's tab (i.e., the order of the folder)
TI=0

Tab size (as defined by user in Folder Properties)
TS=4

Default Note background color
BG=$00DADADA

Default font character set for folder
CH=0

Default font color for folder
FC=clWindowText

Default font name for folder
FN=Courier New

Default font size for folder
FS=12

Default language for folder
LN=1033

Default font style for folder (can include strings: 'bold', 'italic', 'underline', 'strikeout')
ST=bold italic

Flags string (see "FOLDER FLAGS", below)
FL=101110000000000000000000

Number of lines of text (not required, but allows KeyNote to pre-allocate memory, which somewhat improves the speed of loading data into the RTF editor)
LC=2

Index of currently selected note (tree node)
SN=0

Width of the tree panel, in pixels
TW=187

Max width of the tree panel, in pixels
TM=250

Default name for new nodes
EN=New node

Tree panel background color
TB=clWindow

Tree font character set
TH=238

Tree font color
TC=clWindowText

Tree font name
TN=Verdana

Tree font size
TZ=9

Tree font style (format as above: bold, underline, italic, strikeout)
TY=


List of Note NODES inside current Folder
------------------------------------------------------

Number of Note Nodes in folder
n:=45


New Note Node (NNode) starts ----------------------------
%-

Important: "GI" (optionally) and "gi", in this order, are the first fields to save

Optional: Global ID (GID) of the note referenced by the NNode.
It will be only necessary if the NNode is not the first node in the note and so "gi" <> "GI"
(Most Notes only have one associated NNode. Only "linked nodes" share the same note and so have different "gi" )
GI=2

Unique NNode ID (Global ID) in the file.
The Global ID of the first created NNode referencing a note will use the same GID value of the note.
In this case, gi=GI, and so it will be enough to identify the corresponding note.
gi=3

Unique NNode ID within the folder . 
It is only available in Note nodes obtained by conversion from .knt files created with version < 1.9.3.
Since that version (.knt format 2.1) new NNodes are only identified by Global ID ("gi")
DI=1

Node state  (only needed if <> 0)
Is the hexadecimal representation of the options available in each Node, as described below ("NODE STATE")
ns=0801

Node level (indicates nesting). 
Only needed if the level is different than the previous node in the folder (as written in the .knt, i.e. hierarchically)
LV=0


Optional: Editor Background color  (only needed if different to default value in folder)
BC=$00DADADA

Optional: Color for node caption    (only needed if different to default value in folder)
HC=clYellow

Optional: Background color for node caption  (only needed if different to default value in folder)
HB=clRed

Optional: Font name for node caption (only needed if different to default value in folder)
FF=Trajan Pro

Optional: Node image index (if "custom icons" are selected for the tree) (only needed if <> 0)
IX=0


Optional: Alarm instant       (New in 1.7.1)
NA=21-05-2007 15:24:50

 (Since 1.7.8 it is possible to add a subject to the alarm. This subject is encoded in UTF-8 without BOM)
 (Since 1.7.9 program can distinguish between Reminder time and an optional Expiration/Event time and allows to set colors and bold)

 NA=[D]Reminder[/Expiration][*Format][|Subject]
    [] => optional
    D: Discarded
    Expiration or Reminder: DD-MM-YYYY HH:MM:SS
    Format: BoldformatFontcolor/Backcolor
    BoldFormat: B or N   (Bold or Normal)
    FontColor or BackColor: number (TColor)
    Subject: unicode text

 Example:
   NA=D10-06-2010 08:00:00/10-06-2010 07:55:00*B100/1200|I should do something..



--------------------------------------
BOOKMARKS SECTION

  From version 1.8.5, auxiliary bookmarks created with Search|Set Bookmark (Shift+Alt+[0-9]) are saved in file in a new section, at the end
  of the file, but before Image Sections
  Example:
  
%BK
BK=0,file:///*8|2|29|0|1
BK=1,file:///*4|2|29|0|1


--------------------------------------
IMAGE SECTIONS

  From version 1.8.1, in the case of using a image storage mode other than Embedded RTF, the application will use an EXTENDED KNT FORMAT when saving in
  which new blocks have been incorporated at the end of the file, to allow including the registration of stores and images:
  Example:
  
  
%S
SM=2
SD=1|TestIMG_img
%I
II=5
PD=1|NOTE1\|1_Image 24oct.png|1|32|32|343790583||1|6||0
PD=2|NOTE2\|2_Image 24oct.jpg|1|770|649|1481786765||1|3|CORONA|0
PD=3|NOTE2\|3_sample.wmf|5|770|649|1976212572|E:\sample.wmf|1|2||0
PD=4|||1|120|171|1006143828|E:\Avatar.png|0|2||0
%EI
EI=1|1_Image 24oct.png|<size>
<--image in binary-->
##END_IMAGE##
EI=<IDImage>|<FileName>|<size>
<--image in binary-->
##END_IMAGE##
...
%%


%S: Storage section
   SM= Reflects the storage mode.. 0:EmbeddedRTF 1:EmbeddedKNT 2:External 3:ExternalAndEmbeddedKNT	 
	  (Mode 0 will not actually be displayed, since in that case these new blocks will not be used...)
	 
   SD= Type(0:Zip 1:Folder)|Path
	  (Only included with modes 2 and 3)

%I: Image section. Lists information about the images used in the KNT file:
  
   II= Shows the ID to be used for the following image
   PD= IDImg|Path|Name|Format|Width|Height|crc32|OriginalPath|Owned|RefCount|Caption|MustBeSavedExt
		 - IDImg: Each image has a unique numerical ID (>=1)
		 - Path: Relative path to storage, this will normally correspond to the name of an existing note
		 - Name: Unique name of the file within the storage.
		 - Format: 0:GIF, 1:PNG, 2:JPG, 3:BMP, 4:TIF, 5:WMF, 6:EMF
		 - Width, Height: Width and height of the image. Each instance may be using different values.
		 - crc32: Value obtained from the image content. Used to identify if an added image is new or is another instance
				  of one already registered.
		 - Original path: Obtained in the case of insertion from existing files
		 - Owned: 1:Owned by KNT file. Added to one storage. Can be deleted when unused
				  0:Linked. Image is independent. The image is obtained from its original path and neve will be deleted by KNT
		 - ReferenceCount: Number of instances of the image within the KNT file.					  
				When the number of references becomes 0, the image will be deleted (when saving changes) from the %I block
				and the %EI block (the latter if the External or ExternalAndEmbKNT modes are used).
				In the case of using the External or ExternalAndEmbKNT modes (the image being 'owned'), the corresponding
				file will be deleted from the external storage.
				A line in KNT with this field set to 0 indicates that the image has been deleted but is missing from external
				storage, not accessible at the time of saving the KNT file.
				  
		 - Caption: Image title
		 - MustBeSavedExt: 1: Indicates that the image is waiting to be saved to its external storage.
			Its content will be found in the %EI block					  
							
%EI:  Embedded Images		  
	In the case of using smEmbKNT or smExternalAndEmbKNT (fStorageMode: TImagesStorageMode) as storage mode
	The content of each image (except linked ones) will be saved within this block		  
	
	
	
----------

End of file marker follows:
%%




-------------------------------------

NOTES:

1. About "flags" strings.
=========================

Flags strings hold a number of boolean (yes/no) values, and, rarely, other types of values. Each value is encoded as a single character in the flags string. Boolean values are encoded as 0 (false) and 1 (true); for meaning of other values see flag descriptions below.

Each flag string is exactly 24-characters long, and will be IGNORED if it is shorter. (That is, if the string is shorter than 24 characters, KeyNote will not read ANY values from the string.) Not all 24 values are used.

There are two versions of the flags string: one for file and another one for every folder in the file.

The meanings of particular flags and values have changed with subsequent releases of KeyNote. Only the current values and meanings are described here


a) FILE FLAGS   

position	type		meaning
----------  --------    --------------
1           boolean		Open file as read-only
2           boolean		Show icons on tabs
3           boolean		TRUE if file was saved using version 3.0 of the richedit control; otherwise FALSE
4           boolean		TRUE if the multi-level backup setting (Tools|Options) should be IGNORED for this file; otherwise FALSE (i.e. perform multi-level backup if so configured)



b) FOLDER FLAGS

position	type		meaning
----------  --------    --------------
1           boolean		Folder is visible                                                                   (* UNUSED; never been implemented)
2           boolean		Folder is read-only
3           boolean		Word-wrap ON/OFF
4           boolean		URL detection ON/OFF
5           boolean		if TRUE, use true TAB character in this note; 
                        if FALSE, insert spaces instead of TAB character when user presses the TAB key
6           boolean		Default Plain text only  (Folder properties|Editor settings)
                        if TRUE, new notes willl created as "Plain text only" 
7           boolean     if TRUE, filter folder is applied                        (New in 2.0.0)
            
13          integer		Tree icons selector: 0 = No icons; 1 = Standard (default) icons; 2 = Custom icons
14          boolean		Automatic node numbering ON/OFF                                                     (* UNUSED since version 2.0.0)
                        (if TRUE, node number is automatically added to node name when node is created)
15          boolean		Show checkboxes in tree ON/OFF
16          boolean		TRUE = vertical tree layout; FALSE = horizontal tree layout
17          boolean		TRUE = tree panel is hidden; FALSE = tree panel is visible
18          boolean		TRUE = tree panel has focus; FALSE = editor has focus
            
19          boolean		TRUE = Hide checked nodes; FALSE = All nodes are visible  (New in 1.7.0)

20          integer		Date column position     (0: hidden   First column: 1)
21          integer		Flagged column position  (,,)

22          boolean		TRUE = Editor Info panel is visible; FALSE = Editor Info panel is hidden



1. About HEX States
====================

The states described here consist of a series of boolean values, with which a binary number can be built,
which will be saved in the .knt file in its hexadecimal representation.
The boolean values, the digits of the binary number, are described below starting with the lowest value.
Thus, if for example "1110" in binary = 14 in decimal = 0E in hexadecimal, they will be described starting 
with the boolean corresponding to that "0".
To facilitate identification and conversion, "--" is added every four 'bits' or boolean values.
(See examples below)
  

* "Not yet used" implies that it can be changed or even removed. As a rule, in most cases they will be described 
  in more detail, especially in the help file.  
 

c) NOTE STATE

 * Not yet used:
   
    ReadOnly      - Individual note marked as read-only
    Archived      - Individual note marked as archived. 
	                Its a way to mark a note as material that we do not want to appear by default in searches
    ShowEmbedded  - Show as embedded note when viewing the parent note
    NoEmbeddable  - Do not embed, if it is used a presentation mode that represents as embedded notes all or a selection
                   (according to some criteria) of its child notes.

   Ex: Ns=0B    -> 'NoEmbeddable', 'Archived' and 'ReadOnly' -> (1011 -> 11 decimal -> 0B in hexadecimal)



c) Note ENTRY STATE

    Modified    - Always 0 when saving (do not use)
    PlainTXT    - Content is Plain TXT  (if not assigned: content is RTF)
    HTML        - Content is HTML

  * Not yet used:

    ReadOnly       - Entry marked as read-only
   --	
    Encrypted      - Entry marked as encrypted
    Archived       - Entry that we do not want to appear by default in searches or complicate the display of notes
    EntryAndNote   - It allows to point out that an entry also constitutes a note in itself (it is the 'first' entry
                     of that one, or its Main entry, and that it may have other Entries)
    Fixed          - When viewing the note, pin to the top. Can also be used as a search criterion
   --	
					 
 	 * Internal and basic way of categorizing the entries of a note. Can also be used as a search criterion
	   (and complemented with the use of custom tags) :
		  
    IsMain          - Main entry in a note, which identifies the note, usually the first. Its tags will apply globally to the entire note
    IsSummary       - Only one entry can be used as Summary in a note
    IsStarred
    IsRequirements
   --	
    IsDoc
    IsToDO


   Ex: NS=0005   -> 'HTML' and 'PlainTXT'


c) NODE STATE

    Bold                     - The title node (note name) is shown in bold
    TreeFilterMatch          - Fulfills the tree filtering condition (if it exists)
    FindFilterMatch          - ,,           Find All  ,,
    ChildrenCheckbox         - Show checkboxes in children of node
   --
    ShowOutlineNumberAndName - Outline node numbering configured as number and name
    ShowOutlineOnlyNumber    - ,,                                   only number
    CustomNumberingSubtree	 - Node configured as start of numbering subtree
    WordWrap                 - Apply WordWrap in the node
   --
    NoWordWrap               - Do not apply WordWrap in the node  (If neither WordWrap nor NoWordWrap => default value in folder)
    Flagged                  - Node is flagged
    Expanded                 - Node is expanded in the folder tree
    Checked                  - Node is checked
   --	
    Hidden                   - Node is hidden in the folder tree


  Ex: ns=1C00      : 'Hidden' -- and 'Checked' and 'Expanded'  ->  0001 1100 0000 0000 -> 1 C 0 0 
  
	  ns=0409	  ->  0000 0100 0000 1001 ->  'Expanded' -- and 'ChildrenCheckbox' and 'Bold'



-------------------------------------

IMPORTANT NOTES about the RTF/PLAIN TEXT data section:

1. The data section may be empty or missing entirely, which will not invalidate the file. This allows you to easily create file templates without having to worry about supplying valid RTF data: your template can simply define the structure (notes and nodes), while leaving out the data sections, which users will fill in as they create files based on the template.

2. Each entry in a note can be configured and saved as RTF or "Plain text only". In the Folder you can define a default value for new notes, but you 
 can mix RTF and "Plain text only" notes in the same folder.
 When storing plain text data (%> section) we could encounter lines which would be interpreted by KeyNote as section markers (i.e. if the note has a line that consists only of "%*", it would be interpreted as a start of a new note). This cannot happen in RTF data, because there will at least be a trailing backslash or "\par" token, but for plain-text data we MUST avoid the possibility of such conflicts.

 Therefore, in the data section of plain-text note entries KeyNote prepends a semicolon (;) to each data line, like this:

;one line of text in a plain-text note
;another line of text.

These semicolons must be stripped before displaying the text.




--- END ---

======================================================
KEYNOTE 1.x: File Format Specification
Last updated: 12 June 2003

<marek@tranglos.com>
http://www.tranglos.com

Full KeyNote source code and other information is available at:

	http://www.tranglos.com/free/keynote.html
	http://sourceforge.net/projects/keynote/

Marek Jedlinski
<marek@tranglos.com>