Browse files

markdown: Improve documentation

* Add rst README file
* Add some useful screenshots
* Add a generated HTML help file
* Use the plugin_help() feature to load the HTML help file
* Update build system to install help files
  • Loading branch information...
1 parent 9be5443 commit 9fb81fcc2779c0fc28c6790c7ea0acda96ddd45d @codebrainz codebrainz committed Jul 16, 2012
@@ -16,5 +16,6 @@ AC_DEFUN([GP_CHECK_MARKDOWN],
+ markdown/docs/Makefile
@@ -1,4 +1,4 @@
include $(top_srcdir)/build/
-SUBDIRS = discount src
+SUBDIRS = discount src docs
plugin = markdown
@@ -1 +1,174 @@
+.. image:: plugin_small.png
+ :align: center
+ :alt: The Markdown plugin in action
+ :target: plugin.png
+.. contents::
+This plugin provides a real-time preview of rendered Markdown, that is,
+`Markdown <>`_ converted to HTML
+and inserted into an HTML template and loaded into a
+`WebKit <>`_ view.
+ * Allows placing the preview in the sidebar or message window areas
+ * Updates the preview on-the-fly as you type, automatically.
+ * Allows simple customization of fonts and colours and complete control
+ with custom template files.
+The preview is active by default for all documents with a Markdown filetype
+set. To set a document's filetype, choose from the menus:
+.. image:: set_filetype.png
+ :align: center
+ :alt: Choosing Document->Set Filetype->Markup Languages->Markdown source file
+ :target: set_filetype.png
+Other than that the operation should be fully automatic. Use the Plugin
+Preferences mechanism to customize some settings as described below.
+For more information on Markdown syntax, read the
+`Markdown Syntax Documentation
+.. image:: settings.png
+ :align: center
+ :alt: The Markdown plugin's preferences GUI
+ :target: settings.png
+Using Geany's normal Plugin Preferences mechanism, you can customize some
+important settings related to the Markdown preview. The preferences dialog
+allows changing the following settings:
+========= ===================================================================
+Name Description
+========= ===================================================================
+Position The area of Geany's UI to put the preview view, currently either
+ in the sidebar or message window (bottom) areas.
+Font The regular body font of the preview.
+Code Font The font to use for the code tags (monospaced) font of the preview.
+BG Color The preview's background color.
+FG Color The preview's foreground (text) color.
+Template The file containing the HTML template for the preview.
+========= ===================================================================
+There's two ways to access the Plugin settings, one is through the
+Plugin Manager using the buttons highlighted below:
+.. image:: plugin_mgr.png
+ :align: center
+ :alt: The Plugin Manager dialog showing the Help and Preferences buttons.
+ :target: plugin_mgr.png
+Clicking the ``Help`` button opens this document in HTML format in your web
+browser. The other way to access the plugin's preferences is through the
+``Edit`` menu as pictured below:
+.. image:: plugin_prefs.png
+ :align: center
+ :alt: Accessing plugin preferences from the Edit menu.
+ :target: plugin_prefs.png
+*Custom Templates*
+You can provide a custom HTML template file which contains the substitution
+strings that get replaced at run-time. The following substitution strings
+are available:
+============================ ================================================
+Substitution String Description
+============================ ================================================
+``@@markdown@@`` The most important substitution string and
+ gets replaced with the HTML generated from the
+ editor's Markdown buffer. Not having this one
+ in the template makes the plugin completely
+ useless.
+``@@font_name@@`` The normal font family.
+``@@code_font_name@@`` The code/monospace font family.
+``@@font_point_size@@`` The size in points of the normal font.
+``@@code_font_point_size@@`` The size in points of the code/monospace font.
+``@@bg_color@@`` The background color in hex/HTML color notation.
+``@@fg_color@@`` The foreground (text) color in hex/HTML color
+ notation.
+============================ ================================================
+The default template file (at the time of writing) contains the following
+HTML code::
+ <html>
+ <head>
+ <style type="text/css">
+ body {
+ font-family: @@font_name@@;
+ font-size: @@font_point_size@@pt;
+ background-color: @@bg_color@@;
+ color: @@fg_color@@;
+ }
+ code {
+ font-family: @@code_font_name@@;
+ font-size: @@code_font_point_size@@pt;
+ }
+ </style>
+ </head>
+ <body>
+ @@markdown@@
+ </body>
+ </html>
+As you can see it's just normal HTML/CSS and you can tweak it to make the
+preview contents look exactly how you want. The preview view is a WebKit
+browser, the same one used by `Google's Chrome Browser
+<>`_ and `Apple's Safari Browser
+<>`_ as well as numerous others, and it supports many
+modern features such as HTML5 and CSS3 support (at least partially).
+If you mess up the default ``template.html`` file, just delete it and the
+default one will be recreated the next time the Markdown plugin is reloaded
+(for example when Geany restarts).
+The plugin depends on the following libraries:
+ * `GTK+ <>`_ 2.16 or greater
+ * `WebKitGTK+ <>`_ 1.1.18 or greater
+The Markdown plugin is licensed under the GNU General Public License,
+version 2 or (at your option) later versions. For the full text of the
+license, please visit
+The Geany Markdown plugin is written and maintained by::
+ Matthew Brush <matt(at)geany(dot)org>
+The plugin includes the Discount Markdown library, developed by::
+ David Loren Parsons <>
+You can email me at ``matt(at)geany(dot)org``, or find me on the
+``#geany`` IRC channel on FreeNode, with the nickname ``codebrainz``.
@@ -0,0 +1,14 @@
+helpdir = $(docdir)/markdown/html
+help_DATA = \
+ help.html \
+ plugin.png \
+ plugin_mgr.png \
+ plugin_prefs.png \
+ plugin_small.png \
+ set_filetype.png \
+ settings.png
+# To update the HTML help file
+help.html: $(top_srcdir)/markdown/README
+ rst2html $< > $@
Oops, something went wrong.

0 comments on commit 9fb81fc

Please sign in to comment.