This page describes the steps required to create a binder, create and edit single documents and bind the documents together.
While you can edit your documents with any text editor, these instructions assume the use of Notepad++ in Windows which should be configured by now to work with MarkupBinder commands as explained in the installation section.
Documents are written in the Markdown lightweight writing format, the syntax of which you will find in the
Writing your document with Markdown section. At this stage, do not worry about Markdown syntax as only a simple document will be produced to demonstrate the principle; you can learn Markdown in greater detail later.
When you create a new binder, it is configured by default to provide an environment for creating single documents and modifying them in the same way as you would edit documents in a word processor.
A binder is a hierarchical folder structure containing documents. The only requirement from a binder is that the root folder terminates with an underline '_' character.
As a binder is simply a folder, it is convenient to work with a binder from Windows Explorer, the file manager in Windows.
Let's say that you want to create a binder containing your notes about your favourite subject, Geography. You start by creating a folder somewhere on your system with the folder name 'Geography_' (notice the '_' at the end of the name as this is important to tell MarkupBinder where the binder starts). Then you may like to create a set of sub-folders, one for each continent and perhaps under Europe you want to create a document about the UK.
One way to do this is to start Notepad++, write a few lines and save the document with the name 'UK.md' under the folder path:
...\Geography_\Europe\UK.md
Note that the file 'UK.md' has the file extension '.md'. This is essential for MarkupBinder to identify your documents correctly as Markdown files.
In the previous page about using Notepad++, the procedure for configuring your file manager to open Markdown (files with the '.md' file extension) was described. Now press Enter on the file 'UK.md' in Windows Explorer; Notepad++ should start automatically and open with the file loaded.
Since the file is about the UK, you can write a number of lines as follows:
Start of file...
### United Kingdom
The United Kingdom is located in western Europe
and divided into four parts:
- England
- Scotland
- Northern Ireland
- Wales
End of file
Press [Ctrl + s] to save the file but keep Notepad++ open.
To view the newly created file, press [F6] to bring up the NppExec dialog and then select the MarkupBinder command 'Build document page'. If all is well, the file you just created has been formatted automatically to HTML and your default browser (Internet Explorer or Firefox, for example) will open displaying the file you just created.
You will note that the three hash symbols '###' at the beginning of the first line have been replaced by heading level three and all lines starting with '-' (hyphen or dash) have been replaced with a list; these are examples of the way the text formatter converts Markdown to HTML. You will also notice that the way to create a paragraph is to freely type lines of text and the lines are joined together and a paragraph is formatted automatically by any block of text surrounded by empty lines.
After viewing the file, close the browser and you should be back in Notepad++ ready to continue with editing your document.
As you learn to use Markdown, you will be able to write longer chunks of your document before viewing the result in the browser; the whole point of a text formatter as compared with a word processor, is that if you mark your document correctly, formatting should be correct 'out of the box'.
Now that you have created a document successfully about the UK, try to create another document about another country, perhaps in a different continent.
The HTML files you have created by invoking the 'Build Document Page' command above are stored in the same folder together with your Markdown documents. These HTML files are self-contained with a default internal style sheet, your name as the author (if you specified it; more on this later) and the date. You may be happy with this output which you can send perhaps as an email attachment to other people. You may sometimes wish, however, to convert your Markdown file to other formats.
When you invoke a MarkupBinder command, the output is written to the Notepad++ console. If you configured the NppExec 'Toggle console' command as explained in the installation section, you can press [Shift + F6] to reveal or hide the console. If there are any errors, you will find them in the console. You can view the console during or after invoking a MarkupBinder command.
For example, to convert your file to RTF format which can be opened by most word processors, invoke the command 'Convert File'. A dialog appears in the Edit box; type the command:
md2rtf
(Notice the number '2' in the middle of the command, not the word 'to')
A number of common file conversion commands are summarized further below. If all is well, the output console indicates that the conversion has been successful.
As mentioned above, you can hide the console so that you can edit your file again by pressing [Shift + F6].
The file converted above with a '.rtf' file extension is placed next to the other files in the same folder in the binder.
You have learned so far how to create single documents, view them individually in your browser and convert them to other formats.
MarkupBinder allows you to bind your document together into an HTML structure, based on your folder hierarchy, so that you can navigate and view your folders and documents easily. This is done by incorporating headers and footers for navigation in each HTML document; a document file with a header and footer is referred to as a 'content page'. These content pages are connected with index files, one for each folder. It should be noted that the binder structure only affects the HTML files and does not affect the document Markdown files at all.
Assuming you have a Markdown file open in your text editor, use the 'Build Binder' command to create the files for the whole binder or the 'Build Folder' command to create the files for the current folder and its sub-folders if relevant.
If you examine your binder, you will find an index file 'index.html' at the root of the binder (in the example above: ...\Geography_\index.html). If you click on the file, your default browser will open with this file and you can easily navigate the binder. Each of the content (document) pages now contains a header at the top of the page which shows the section path of where you are in the binder. The navigation footer at the bottom of the page will enable you to navigate to the next and previous pages as well as up the binder hierarchy. You will find an index page in each folder.
The binder root folder contains a sub-folder called '_resource' which contains all the configuration files which control the binder structure.
Under the '_resource' sub-folder you will find a file called 'empty file.md'. This file is, as the name implies, an empty file configured to support characters in UTF-8 encoding required to display special characters correctly after conversion. To ensure correct representation of all characters, it is convenient whenever you want to start a new document file to simply copy this empty file to the binder folder (the parent folder of the '_resource' sub-folder), change its name to the name you want (but leave the file extension as '.md') and open the file in the usual way in Notepad++.
If you examine each of the folders in the binder with Windows Explorer (assuming you have created a number of documents), you will find usually that folders and files are ordered alphabetically, with folders first followed by files. When you navigate your binder using the index files, by default the order of the folders and files is similar to the one in your file manager. This order may suit your needs but you may prefer to order your folders and files in a different way. This is easily done by changing the order of these in the 'order.txt' file located in the '_resource' sub-folder created automatically after you run any of the binder commands the first time.
In some situations you may want to remove all the HTML files and other formats created with the commands above because these files are no longer required or because you want to rebuild the binder from scratch. To do this use the 'Clean Binder' command.
Every newly created binder is configured by default for editing single documents and binding them together if desired. All HTML files point to or contain a default style sheet optimized for document viewing and good accessibility, and are marked with the last editing date. The only thing you might want to specify is the author name.
All binder configurations are done by editing the binder-properties.txt file located in the '_properties' sub-folder under the '_resource' sub-folder. So for the example above, the file is at:
...\Geography_\_resource\_properties\binder-properties.txt
Edit the file in Notepad++, locate the line:
author.name=none
Change it to:
author.name=Your name
Save and close the file.
So far, the HTML binder files have been created in the binder itself occupying the same folders as the original document Markdown files. This is convenient for a situation where you create local files for local viewing as a binder (of course, you can convert each Markdown file individually and send this to anybody you want). You may want to publish your binder to the web in which case you want all your HTML binder files in the same folder and to be web compatible meaning that file names do not include spaces. To do this, invoke the 'Build Web Binder' command. You will notice that a new folder is created alongside your binder folder with the suffix '-Web'; so for the example above, the new folder is called 'Geography-Web'. In this folder you will find only HTML files, and spaces in folders and file names have been replaced with '_' (underline). You can transfer this web-ready binder to your website if you wish.
You can always display this Manual in your default web browser by invoking the 'MarkupBinder Help' command.
Assuming you have learned the Markdown syntax as explained in the next section, the above information should get you started with editing single documents in MarkupBinder and in many cases this is all you need to know. Should you require more information on the binder structure and configuration, read the remaining pages in the
Creating, editing and binding your documents with MarkupBinder section.
md2rtf
Converts Markdown to Rich Text Format (read by most word processors)
md2odt
Converts Markdown to an OpenOffice text document
md2odf
Converts Markdown to OpenDocument XML (increasingly supported by word processors)
html2md
Converts HTML to Markdown (useful for converting existing HTML files to Markdown)
md2mdp
Converts (reformats) Markdown to the Pandoc flavour of Markdown (experimental)
Note that the file converted is suffixed with '-f.md' to distinguish it from the original Markdown file.
[ Next - Getting started with multi-document structured publications ]
[ Previous - Using MarkupBinder with Notepad++ ]
[ Up - Getting started with MarkupBinder using Notepad++ - Section ]
[ Up 2 - Getting started with MarkupBinder in Windows - Section ]
[ Up 3 - Creating, editing and binding your documents with MarkupBinder - Section ]