(zettel (meta (back "00001000000000") (backward "00001000000000 00001006050000") (box-number "1") (created "20210126175322") (forward "00000000020001 00000000040001 00001002000000 00001004010000 00001004020000 00001005090000 00001006050000 00001012000000 00001012053200 00001014000000") (modified "20241213101751") (published "20241213101751") (role "manual") (syntax "zmk") (tags "#design #manual #zettelstore") (title "Structure of Zettelstore")) (rights 4) (encoding "") (content "Zettelstore is a software that manages your zettel.\nSince every zettel must be readable without any special tool, most zettel has to be stored as ordinary files within specific directories.\nTypically, file names and file content must comply to specific rules so that Zettelstore can manage them.\nIf you add, delete, or change zettel files with other tools, e.g. a text editor, Zettelstore will monitor these actions.\n\nZettelstore provides additional services to the user.\nVia the builtin [[web user interface|00001014000000]] you can work with zettel in various ways.\nFor example, you are able to list zettel, to create new zettel, to edit them, or to delete them.\nYou can view zettel details and relations between zettel.\n\nIn addition, Zettelstore provides an \"\"application programming interface\"\" ([[API|00001012000000]]) that allows other software to communicate with the Zettelstore.\nZettelstore becomes extensible by external software.\nFor example, a more sophisticated user interface could be built, or an application for your mobile device that allows you to send content to your Zettelstore as new zettel.\n\n=== Where zettel are stored\n\nYour zettel are stored typically as files in a specific directory.\nIf you have not explicitly specified the directory, a default directory will be used.\nThe directory has to be specified at [[startup time|00001004010000]].\nNested directories are not supported (yet).\n\nEvery file in this directory that should be monitored by Zettelstore must have a file name that begins with 14 digits (0-9), the [[zettel identifier|00001006050000]].\nIf you create a new zettel via the [[web user interface|00001014000000]] or via the [[API|00001012053200]], the zettel identifier will be the timestamp of the current date and time (format is ''YYYYMMDDhhmmss'').\nThis allows zettel to be sorted naturally by creation time.\n\nSince the only restriction on zettel identifiers are the 14 digits, you are free to use other digit sequences.\nThe [[configuration zettel|00001004020000]] is one prominent example, as well as these manual zettel.\nYou can create these special zettel by manually renaming the underlying zettel files.\n\nIt is allowed that the file name contains other characters after the 14 digits.\nThese are ignored by Zettelstore.\n\nTwo filename extensions are used by Zettelstore:\n# ''.zettel'' is a format that stores metadata and content together in one file,\n# the empty file extension is used, when the content must be stored in its own file, e.g. image data;\n  in this case, the filename just the 14 digits of the zettel identifier, and optional characters except the period ''\".\"''.  \nOther filename extensions are used to determine the \"\"syntax\"\" of a zettel.\nThis allows to use other content within the Zettelstore, e.g. images or HTML templates.\n\nFor example, you want to store an important figure in the Zettelstore that is encoded as a ''.png'' file.\nSince each zettel contains some metadata, e.g. the title of the figure, the question arises where these data should be stores.\nThe solution is a meta-file with the same zettel identifier, but without a filename extension.\nZettelstore recognizes this situation and reads in both files for the one zettel containing the figure.\nIt maintains this relationship as long as these files exists.\n\nIn case of some textual zettel content you do not want to store the metadata and the zettel content in two different files.\nHere the ''.zettel'' extension will signal that the metadata and the zettel content will be put in the same file, separated by an empty line or a line with three dashes (\"\"''-\\-\\-''\"\", also known as \"\"YAML separator\"\").\n\n=== Predefined zettel\n\nZettelstore contains some [[predefined zettel|00001005090000]] to work properly.\nThe [[configuration zettel|00001004020000]] is one example.\nTo render the builtin [[web user interface|00001014000000]], some templates are used, as well as a [[layout specification in CSS|00000000020001]].\nThe icon that visualizes a broken image is a [[predefined GIF image|00000000040001]].\nAll of these are visible to the Zettelstore as zettel.\n\nOne reason for this is to allow you to modify these zettel to adapt Zettelstore to your needs and visual preferences.\n\nWhere are these zettel stored?\nThey are stored within the Zettelstore software itself, because one [[design goal|00001002000000]] was to have just one executable file to use Zettelstore.\nBut data stored within an executable program cannot be changed later[^Well, it can, but it is a very bad idea to allow this. Mostly for security reasons.].\n\nTo allow changing predefined zettel, both the file store and the internal zettel store are internally chained together.\nIf you change a zettel, it will be always stored as a file.\nIf a zettel is requested, Zettelstore will first try to read that zettel from a file.\nIf such a file was not found, the internal zettel store is searched secondly.\n\nTherefore, the file store \"\"shadows\"\" the internal zettel store.\nIf you want to read the original zettel, you have to delete the zettel (which removes it from the file directory).\nNow we have two places where zettel are stored: in the specific directory and within the Zettelstore software.\n\n* [[List of predefined zettel|00001005090000]]\n\n=== Boxes: alternative ways to store zettel\nAs described above, a zettel may be stored as a file inside a directory or inside the Zettelstore software itself.\nZettelstore allows other ways to store zettel by providing an abstraction called __box__.[^Formerly, zettel were stored physically in boxes, often made of wood.]\n\nA file directory which stores zettel is called a \"\"directory box\"\".\nBut zettel may be also stored in a ZIP file, which is called \"\"file box\"\".\nFor testing purposes, zettel may be stored in volatile memory (called __RAM__).\nThis way is called \"\"memory box\"\".\n\nOther types of boxes could be added to Zettelstore.\nWhat about a \"\"remote Zettelstore box\"\"?"))