Creating, editing and binding your documents with MarkupBinder >


Binder folder structure

This page gives details of the binder structure and its uses. Some of the topics here have been covered in the 'getting started' pages.

A binder is a hierarchical folder structure containing documents. These can be either individual documents much the same as you would produce with a word processor or these documents can be part of a structured publication such as a manual or a tutorial.

The only requirement from a binder is that the root folder terminates with an underline '_' character.

If you use a binder to group individual documents, folder names represent logical groupings of these documents. If you are using a binder to represent a single structured publication, folder names are the same as the names of the corresponding sections and sub-sections in your publication.

Documents in the binder (the content) are simple text files with the file extension '.md'. These files are written with the Markdown lightweight writing format.

The most convenient way of using MarkupBinder is as a series of tools configured in a text editor. Alternatively MarkupBinder can be used from the command line if you wish.

Each document is edited in a text editor and then, with a command issued with a simgle keystroke, converted to HTML and displayed in a browser. During the editing / preview phase, each document is converted individually and appears as a direct conversion of the original Markdown file and is referred to as a document page. This file can be used on its own as it contains an internal style sheet and information such as the author and date.

Once the documents are bound together in HTML using a number of single keystroke commands, each document file is augmented with a section path header and navigation footer and forms what is termed 'a content page'. These documents (individual or part of a structured publication) are linked together automatically for easy viewing using index files.

You use the binder's folder to edit your Markdown documents and files converted to HTML are stored during the editing phase together with the Markdown files; this way you can always review the HTML output either individually or using the index HTML files.

You can modify your binder folder structure as you go along, modify Markdown (content) file names and, of course, update the file content. You can combine folders from other binders and MarkupBinder will combine these automatically to form an HTML binder structure.

As described above, individual documents are displayed during the editing / preview phase in HTML but you can convert files written in the Markdown format to other formats such as RTF and ODT for viewing in word processors. You can also convert files in other formats such as HTML to Markdown.

To start a binder from scratch, after marking the root of the binder with the character '_' at the end of its name as described above, you may create sub-folders as appropriate. Then create a new text file with the file extension '.md'. and save it somewhere in your newly created binder folder structure. With the file still displayed in the text editor, invoke one of the MarkupBinder commands. Besides converting the file to HTML and generating the index, you will notice that each folder now contains a sub-folder called '_resource'. This sub-folder contains various files and folders generated automatically by the system which allow you to customize various aspects of your binder; these are explained later in detail in this manual.

Each '_resource' sub-folder contains a file called 'empty-file.md'. This file, as the name implies, is an empty file saved in utf-8 character encoding required by the format converter to represent correctly characters above US ASCII (characters 128 and above). This file is marked with an identifier called a BOM, used widely in Windows OS. Regardless of whether you are using Windows or Linux, you will find it convenient whenever you want to start another document file to copy this file to the appropriate folder, change its name to suit your needs and open your text editor with this file from your file manager.

If you want to exclude a folder from the binder's HTML structure, simply precede the folder name with an underline '_' character. This can be useful if you want for example to 'park' documents that need working on later or converting to Markdown; the author uses for this purpose a folder called '_temp'.

In the binder folder structure, all content folders must end with the '.md' file extension and only these files are processed. All configuration file names end with the '.txt' extension. This arrangement is made so that you can employ search tools in your file manager to locate text in the content by restricting the search to files with the '.md' extension. It is recommended that you don't mix any other file types in your binder (unless they are located in a folder starting with the character underline '_' which means that they are not processed). Under some circumstances other types of files are removed automatically by the system to reduce clutter.

During the editing phase, you will work inside the binder for both editing the Markdown (content) files and viewing them in HTML. You may store your documents this way anyway for your own use or you may convert the binder to a 'Web ready' folder which is given the same name as the binder but with the terminating '_' character replaced by a '-Web' suffix. You can then upload this folder to your web site using, for example, FTP.


[ Next - Customizing your binder ]

[ Previous - Getting started with MarkupBinder in Linux - no longer maintained - Section ]

[ Up - Creating, editing and binding your documents with MarkupBinder - Section ]

[ Up 2 - MarkupBinder Manual - Main Index ]