This page describes the steps required to create a binder, creating and editing single documents and binding the documents together.
While you can edit your documents with any text editor, these instructions assume the use of gedit in Vinux which should be configured to work by the installer.
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 modify 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 Nautilus the file manager in Vinux.
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 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 gedit, 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.
In the previous page about using gedit, 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 your file manager; gedit 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
You may wish to press [Ctrl + s] to save the file but keep gedit open.
To view the new file created, invoke the MarkupBinder command 'Build document page' by pressing [Ctrl + 1] in gedit. If all is well, the file you just created has been formatted automatically to HTML and Firefox will open displaying the file you just created. (Note that because of a bug in Orca / Firefox, you have to press [Ctrl + F5] in Firefox to display the page.)
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 Firefox and you should be back in your text editor 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 marked your document correctly, formatting should be correct 'out of the box'.
Now that you have created a document successfully about the United Kingdom, 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 is 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 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 others. You may sometimes wish, however, to convert your Markdown file to other formats.
For example, to convert your file to RTF format which can be opened by most word processors, invoke the command 'Convert File' [Ctrl + 6]. 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, you will be informed by speech that the conversion is successful.
The output of any tool notifies you of success or failure and more information is available in the gedit output console which is read only. If the command is unsuccessful, you will need to switch the Orca 'flat navigation review' mode On (Orca + p) and find the console with the flat review keys. Usually, commands are successful and there is no need to review the console output.
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' [Ctrl + 3] command to create the files for the whole binder or the 'Build Folder' [Ctrl + 2] 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, Firefox 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 '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 your text editor.
If you examine each of the folders in the binder with your file manager (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' [Ctrl + 5] command.
Every newly created binder is configured by default for editing single document 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 your text editor, 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' [Ctrl + 4] 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 Firefox by invoking the 'MarkupBinder Help' [Ctrl + 7] 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 gedit ]
[ Up - Getting started with MarkupBinder in Linux - no longer maintained - Section ]
[ Up 2 - Creating, editing and binding your documents with MarkupBinder - Section ]