| 1 |
Markdown |
| 2 |
======== |
| 3 |
|
| 4 |
.. image:: plugin_small.png |
| 5 |
:align: center |
| 6 |
:alt: The Markdown plugin in action |
| 7 |
:target: plugin.png |
| 8 |
|
| 9 |
.. contents:: |
| 10 |
|
| 11 |
About |
| 12 |
----- |
| 13 |
|
| 14 |
This plugin provides a real-time preview of rendered Markdown, that is, |
| 15 |
`Markdown <http://daringfireball.net/projects/markdown>`_ converted to HTML |
| 16 |
and inserted into an HTML template and loaded into a |
| 17 |
`WebKit <http://www.webkit.org>`_ view. |
| 18 |
|
| 19 |
Features |
| 20 |
-------- |
| 21 |
|
| 22 |
* Allows placing the preview in the sidebar or message window areas |
| 23 |
* Updates the preview on-the-fly as you type, automatically. |
| 24 |
* Allows simple customization of fonts and colours and complete control |
| 25 |
with custom template files. |
| 26 |
|
| 27 |
Usage |
| 28 |
----- |
| 29 |
|
| 30 |
The preview is active by default for all documents with a Markdown filetype |
| 31 |
set. To set a document's filetype, choose from the menus: |
| 32 |
|
| 33 |
.. image:: set_filetype.png |
| 34 |
:align: center |
| 35 |
:alt: Choosing Document->Set Filetype->Markup Languages->Markdown source file |
| 36 |
:target: set_filetype.png |
| 37 |
|
| 38 |
Other than that the operation should be fully automatic. Use the Plugin |
| 39 |
Preferences mechanism to customize some settings as described below. |
| 40 |
|
| 41 |
For more information on Markdown syntax, read the |
| 42 |
`Markdown Syntax Documentation |
| 43 |
<http://daringfireball.net/projects/markdown/syntax>`_. |
| 44 |
|
| 45 |
*Preferences* |
| 46 |
^^^^^^^^^^^^^ |
| 47 |
|
| 48 |
.. image:: settings.png |
| 49 |
:align: center |
| 50 |
:alt: The Markdown plugin's preferences GUI |
| 51 |
:target: settings.png |
| 52 |
|
| 53 |
Using Geany's normal Plugin Preferences mechanism, you can customize some |
| 54 |
important settings related to the Markdown preview. The preferences dialog |
| 55 |
allows changing the following settings: |
| 56 |
|
| 57 |
========= =================================================================== |
| 58 |
Name Description |
| 59 |
========= =================================================================== |
| 60 |
Position The area of Geany's UI to put the preview view, currently either |
| 61 |
in the sidebar or message window (bottom) areas. |
| 62 |
Font The regular body font of the preview. |
| 63 |
Code Font The font to use for the code tags (monospaced) font of the preview. |
| 64 |
BG Color The preview's background color. |
| 65 |
FG Color The preview's foreground (text) color. |
| 66 |
Template The file containing the HTML template for the preview. |
| 67 |
========= =================================================================== |
| 68 |
|
| 69 |
There's two ways to access the Plugin settings, one is through the |
| 70 |
Plugin Manager using the buttons highlighted below: |
| 71 |
|
| 72 |
.. image:: plugin_mgr.png |
| 73 |
:align: center |
| 74 |
:alt: The Plugin Manager dialog showing the Help and Preferences buttons. |
| 75 |
:target: plugin_mgr.png |
| 76 |
|
| 77 |
Clicking the ``Help`` button opens this document in HTML format in your web |
| 78 |
browser. The other way to access the plugin's preferences is through the |
| 79 |
``Edit`` menu as pictured below: |
| 80 |
|
| 81 |
.. image:: plugin_prefs.png |
| 82 |
:align: center |
| 83 |
:alt: Accessing plugin preferences from the Edit menu. |
| 84 |
:target: plugin_prefs.png |
| 85 |
|
| 86 |
*Custom Templates* |
| 87 |
^^^^^^^^^^^^^^^^^^ |
| 88 |
|
| 89 |
You can provide a custom HTML template file which contains the substitution |
| 90 |
strings that get replaced at run-time. The following substitution strings |
| 91 |
are available: |
| 92 |
|
| 93 |
============================ ================================================ |
| 94 |
Substitution String Description |
| 95 |
============================ ================================================ |
| 96 |
``@@markdown@@`` The most important substitution string and |
| 97 |
gets replaced with the HTML generated from the |
| 98 |
editor's Markdown buffer. Not having this one |
| 99 |
in the template makes the plugin completely |
| 100 |
useless. |
| 101 |
``@@font_name@@`` The normal font family. |
| 102 |
``@@code_font_name@@`` The code/monospace font family. |
| 103 |
``@@font_point_size@@`` The size in points of the normal font. |
| 104 |
``@@code_font_point_size@@`` The size in points of the code/monospace font. |
| 105 |
``@@bg_color@@`` The background color in hex/HTML color notation. |
| 106 |
``@@fg_color@@`` The foreground (text) color in hex/HTML color |
| 107 |
notation. |
| 108 |
============================ ================================================ |
| 109 |
|
| 110 |
The default template file (at the time of writing) contains the following |
| 111 |
HTML code:: |
| 112 |
|
| 113 |
<html> |
| 114 |
<head> |
| 115 |
<style type="text/css"> |
| 116 |
body { |
| 117 |
font-family: @@font_name@@; |
| 118 |
font-size: @@font_point_size@@pt; |
| 119 |
background-color: @@bg_color@@; |
| 120 |
color: @@fg_color@@; |
| 121 |
} |
| 122 |
code { |
| 123 |
font-family: @@code_font_name@@; |
| 124 |
font-size: @@code_font_point_size@@pt; |
| 125 |
} |
| 126 |
</style> |
| 127 |
</head> |
| 128 |
<body> |
| 129 |
@@markdown@@ |
| 130 |
</body> |
| 131 |
</html> |
| 132 |
|
| 133 |
As you can see it's just normal HTML/CSS and you can tweak it to make the |
| 134 |
preview contents look exactly how you want. The preview view is a WebKit |
| 135 |
browser, the same one used by `Google's Chrome Browser |
| 136 |
<http://google.com/chrome>`_ and `Apple's Safari Browser |
| 137 |
<http://apple.com/safari>`_ as well as numerous others, and it supports many |
| 138 |
modern features such as HTML5 and CSS3 support (at least partially). |
| 139 |
|
| 140 |
If you mess up the default ``template.html`` file, just delete it and the |
| 141 |
default one will be recreated the next time the Markdown plugin is reloaded |
| 142 |
(for example when Geany restarts). |
| 143 |
|
| 144 |
Requirements |
| 145 |
------------ |
| 146 |
|
| 147 |
The plugin depends on the following libraries: |
| 148 |
|
| 149 |
* `GTK+ <http://www.gtk.org>`_ 3.0 or greater |
| 150 |
* `WebKitGTK+ <http://webkitgtk.org>`_ API 4.0 or 4.1 |
| 151 |
|
| 152 |
License |
| 153 |
------- |
| 154 |
|
| 155 |
The Markdown plugin is licensed under the GNU General Public License, |
| 156 |
version 2. For the full text of the license, please visit |
| 157 |
http://www.gnu.org/licenses/gpl-2.0.html. The GPL license covers all code |
| 158 |
and files *not* in the ``discount`` directory. |
| 159 |
|
| 160 |
All code inside the ``discount`` directory is under a BSD-style license |
| 161 |
(see the ``discount/COPYRIGHT`` file) and all contributions to this code |
| 162 |
*will* remain under this license. This will make it easier to integrate |
| 163 |
improvements to Discount back upstream if it ever makes sense. So far the |
| 164 |
only changes are superficial to allow it to build with the Geany-Plugins |
| 165 |
build system and to prevent some compiler warnings. |
| 166 |
|
| 167 |
Authors |
| 168 |
------- |
| 169 |
|
| 170 |
The Geany Markdown plugin is written and maintained by:: |
| 171 |
|
| 172 |
Matthew Brush <matt(at)geany(dot)org> |
| 173 |
|
| 174 |
The plugin includes the Discount Markdown library, developed by:: |
| 175 |
|
| 176 |
David Loren Parsons <http://www.pell.portland.or.us/~orc> |
| 177 |
|
| 178 |
Contact |
| 179 |
------- |
| 180 |
|
| 181 |
You can email me at ``matt(at)geany(dot)org``, or find me on the |
| 182 |
``#geany`` IRC channel on FreeNode, with the nickname ``codebrainz``. |