From d99608f073a88dab41116042aa5252ff0e556346 Mon Sep 17 00:00:00 2001
From: Darwin Darakananda <darwindarak@gmail.com>
Date: Wed, 15 Jul 2015 22:29:33 -0700
Subject: [PATCH] Add README

---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6cedd8c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# Bibliography and Citation support for Python-Markdown
+
+This extension to Python Markdown is inspired by the support for citations in [R Markdown][].
+It looks for all citation keys with the form `@<citekey>` inside matching square brackets and appends a bibliography to the output.
+The references associated with the citation keys can be defined manually or generated from a BibTeX file.
+
+## Installation
+
+Running 
+
+```bash
+$ python setup.py build
+$ python setup.py install
+```
+
+will install a module named `mdx_bib`.
+
+```python
+import markdown
+from mdx_bib import CitationExtension
+
+cite = CitationExtension(bibtex_file='library.bib', order='unsorted')
+html = markdown.markdown(text, extensions=[cite])
+```
+
+## Syntax
+
+Citation keys are any identifiers inside square brackets with a `@`-prefix
+
+```markdown
+Some claim [see @adams98].
+
+Some claim [@adams98; @barney04].
+```
+
+The first line will be converted
+
+```html
+<p>Some claim [see <a id="cite-adams98" href="#ref-adams98" class="citation>@adams98</a>.</p>
+```
+
+This extension will first look for any manually defined bibligraphy entries, for example
+
+```markdown
+[@barney04]: Barneby, C.D. *A review of reviews*. Annual Reviews of Something (2104)
+```
+
+If a matching reference definition cannot be found, then the extension looks in the BibTeX file for a matching citation key.
+
+[R Markdown]: http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html
+