Binder customization is done by editing files located in the 'resource' folder which is generated automatically when you run any of MarkupBinder's commands for the first time. All files and sub-folders in this folder provide configuration of some kind; some are available in the 'resource' sub-folder of the binder root folder and affect the entire binder and some are available in each folder '_resource' sub-folder.
When you start a new folder or create sub-folders, the necessary configurations are generated for the first time automatically containing sensible default values; in many cases you will not need to touch these.
When you write a document in Markdown and run the 'Build Document Page' command, a document page in HTML is created which is the exact formatted and converted version of the document you have created (no binder header or footer). This page is referred to as a 'Document page'.
A binder when built (linked together), contains the following types of pages (files):
Front - the front index page of the binder
Content - pages containing the documents you write, together with a section path header and a navigation footer
Section - index pages connecting the front page with content pages and other section pages
Optional Insert files - the content is inserted into the front and section index pages.
The front and section page files are always called index.html; the front page is located in the root folder of the binder. Some of the settings described below refer to the above five types of pages.
When you edit the binder using a file manager, the files usually appear in alphabetical order determined by the settings of your file manager; this is convenient for locating files quickly. In Windows Explorer for example, the _resource sub-folder appears at the top and the cascading style sheets (files with the '.css' file extension) are located at the bottom (this is why the names of these files start with the characters 'zz' to keep them out of the way). The author tends to keep the files sorted alphabetically regardless of their file extension and this way, each Markdown file is located adjacent to its HTML counterpart making it easy for viewing.
In your binder you may want to change the order of these files and folders to correspond with the logical structure of your publication and this can be done by editing the order.txt file.
The order.txt file always contains the files and sub-folders in the folder of the binder you are editing. If you remove a file or folder or change its name, the order.txt file is updated automatically meaning that this file is always a true reflection of your current folder in the binder. However, the order of files and folders in the order.txt file does not change unless you modify a file or folder name, in which case the name of the file or folder is added to the end.
To change the order of files and folders, simply open the order.txt file in your text editor and change the files' and folders' order to suit your needs. Note that if you remove a file or folder by mistake from the file, it will be appended automatically the next time you run a MarkupBinder command.
By default, every index file contains three parts:
Header - contains the name of the binder itself or a section indicator
Body - links to sub-sections and content pages
Footer - links to next, previous files and folders, and links to sections upstream and the front page of the binder.
You can insert additional content in these pages by creating insert content files as follows:
Create a new content file with the name suffixed with '-insert.md' for example if you want to insert a file with copyright notice you can call it 'copyright-insert.md'. Edit the file and write in Markdown the information you wish to insert.
Run the Build Folder or Build Binder commands to make sure this file name is included in the order.txt file and then edit it to change the order so that the Insert file is in the place where you want the information (copyright information in the example above) inserted.
Run the Build folder or binder commands again and examine the relevant index.html file; the content of the insert file should be inserted in the right place. Note that you need to use the relevant Markdown separation between elements format rules to ensure separation between your insert file and any links above or below in the index file.
In the 'resource/properties' sub-folder of the root folder of the binder, you will find a file called binder-properties.txt. This file contains properties which are clearly commented, containing a key followed by an equals sign '=' followed by a value; simply change the value (on the right side of the '=' sign) to suit your needs.
For example, to change the title of the content pages as displayed in the browser's caption (top of the browser page above the tool and address bar), change the default:
tree.content.title=Note (suitable if your binder contains notes)
to
tree.content.title=Topic (suitable if your binder is a manual)Similar settings are available for the front, section and document pages.
A binder content page contains the written document together with a section path header and navigation footer as indicated above. When you build a document page either on its own with the 'Build Document Page' command or as part of the binder with any of the other build commands, by default the name of the document (the main heading of the page as appears at the top) needs to be specifically written in the document. It is convenient, especially for structured publications, to configure MarkupBinder so that the document name is derived automatically from the file name; this way you can be sure that the file name and its document name (main heading) correspond.
To do this change the default property:
document.name.auto=false
To:
document.name.auto=trueBy default, an automatically derived document name appears as level three; this works well with the binder section path header in content pages but you can change this level heading to any size you want between 1 and 6 using the property provided.
Among other things, you can also change the debug mode of MarkupBinder from false (no debug information) to true (where more information is displayed as MarkupBinder processes your binder).
In the 'resource' sub-folder of the root folder of the binder, you will find four template files which control the style of the HTML pages. These files are named to correspond with the front, section, content and document pages. For example, the file zz-tree-section-template.txt contains the style of all section pages in the binder. The syntax of these files is a standard HTML '.css' file and is self-explanatory. Note that you must edit these template files in the 'resource' folder to affect style changes and not the css files themselves as these will be overwritten during binder processing.
Note also that the document style sheet template file contains the internal style sheet inserted in single document pages.
By default, only the 'resource' sub-folder of the root binder folder contains these style configuration files and these affect all files of their type in the binder. If you want a different style for a section of the binder, simply copy the appropriate style template file and place it in the 'resource' sub-folder of the binder's folder you want the style to apply to (of course after modifying the style configuration file to the style you need).
MarkupBinder uses by default folder names for the names of the binder itself (root folder) and sections. Similarly, Content file names are used to name the content itself.
This default arrangement is useful in many situations but you might find it convenient to use shorter folder and files names and associate these folder and file names with aliases. An advantage of using shorter folder and file names is shorter folder and file paths which are in turn translated to shorter URL's if you want to post your binder on the internet. Alias names are also useful if you want to name sections and content with characters which can't be used in folder and file names.
To create an alias for the Binder name itself, edit the 'binder.alias' property in the 'binder-properties.txt' file mentioned above, replacing 'none' with your desired name.
Creating an alias for a folder and content file is slightly more involved. Every folder and content file can optionally have a property file associated with it; this file contains the alias property you need to change.
First you need to create the properties file; you can do this manually but the naming of this file is important so use the following method:
Open the 'order.txt' file and put an '*' 'asterisk' at the end of the folder or file you want to create a property file for.
Run either the 'Build Folder' or 'Build Binder' commands. If you examine the 'resource/properties' sub-folder you will find the properties file you need which was created automatically based on the '*' marker as mentioned above.
Note that for a folder, a file called 'folder-properties.txt' is created in the '/resource/properties' of the folder in question. For a content file the properties file is created with the suffix '-properties.txt' in the folder where the file is located.
After you run the 'Clean' command followed by any of the binder's commands again, you will find that relevant name is replaced with the alias name you specified.
[ Next - Using MarkupBinder from the command line ]
[ Previous - Binder folder structure ]
[ Up - Creating, editing and binding your documents with MarkupBinder - Section ]