plugins/markdown/README.md

   1 ## Markdown Shaarli plugin
   2
   3 Convert all your shaares description to HTML formatted Markdown.
   4
   5 [Read more about Markdown syntax](http://daringfireball.net/projects/markdown/syntax).
   6
   7 Markdown processing is done with [Parsedown library](https://github.com/erusev/parsedown).
   8
   9 ### Installation
  10
  11 As a default plugin, it should already be in `tpl/plugins/` directory.
  12 If not, download and unpack it there.
  13
  14 The directory structure should look like:
  15
  16 ```
  17 --- plugins
  18   |--- markdown
  19      |--- help.html
  20      |--- markdown.css
  21      |--- markdown.meta
  22      |--- markdown.php
  23      |--- README.md
  24 ```
  25
  26 To enable the plugin, just check it in the plugin administration page.
  27
  28 You can also add `markdown` to your list of enabled plugins in `data/config.json.php`
  29 (`general.enabled_plugins` list).
  30
  31 This should look like:
  32
  33 ```
  34 "general": {
  35   "enabled_plugins": [
  36     "markdown",
  37     [...]
  38   ],
  39 }
  40 ```
  41
  42 Parsedown parsing library is imported using Composer. If you installed Shaarli using `git`,
  43 or the `master` branch, run
  44
  45     composer update --no-dev --prefer-dist
  46
  47 ### No Markdown tag
  48
  49 If the tag `nomarkdown` is set for a shaare, it won't be converted to Markdown syntax.
  50
  51 > Note: this is a special tag, so it won't be displayed in link list.
  52
  53 ### HTML rendering
  54
  55 Markdown support HTML tags. For example:
  56
  57     > <strong>strong</strong><strike>strike</strike>
  58
  59 Will render as:
  60
  61 > <strong>strong</strong><strike>strike</strike>
  62
  63 If you want to shaare HTML code, it is necessary to use inline code or code blocks.
  64
  65 **If your shaared descriptions containing HTML tags before enabling the markdown plugin,
  66 enabling it might break your page.**
  67
  68 > Note: HTML tags such as script, iframe, etc. are disabled for security reasons.
  69
  70 ### Known issue
  71
  72 #### Redirector
  73
  74 If you're using a redirector, you *need* to add a space after a link,
  75 otherwise the rest of the line will be `urlencode`.
  76
  77 ```
  78 [link](http://domain.tld)-->test
  79 ```
  80
  81 Will consider `http://domain.tld)-->test` as URL.
  82
  83 Instead, add an additional space.
  84
  85 ```
  86 [link](http://domain.tld) -->test
  87 ```
  88
  89 > Won't fix because a `)` is a valid part of an URL.