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 escape
  54
  55 By default, HTML tags are escaped. You can enable HTML tags rendering
  56 by setting `security.markdwon_escape` to `false` in `data/config.json.php`:
  57
  58 ```json
  59 {
  60   "security": {
  61     "markdown_escape": false
  62   }
  63 }
  64 ```
  65
  66 With this setting, Markdown support HTML tags. For example:
  67
  68     > <strong>strong</strong><strike>strike</strike>
  69
  70 Will render as:
  71
  72 > <strong>strong</strong><strike>strike</strike>
  73
  74
  75 **Warning:**
  76
  77   * This setting might present **security risks** (XSS) on shared instances, even though tags
  78   such as script, iframe, etc should be disabled.
  79   * If you want to shaare HTML code, it is necessary to use inline code or code blocks.
  80   * If your shaared descriptions contained HTML tags before enabling the markdown plugin,
  81 enabling it might break your page.
  82
  83 ### Known issue
  84
  85 #### Redirector
  86
  87 If you're using a redirector, you *need* to add a space after a link,
  88 otherwise the rest of the line will be `urlencode`.
  89
  90 ```
  91 [link](http://domain.tld)-->test
  92 ```
  93
  94 Will consider `http://domain.tld)-->test` as URL.
  95
  96 Instead, add an additional space.
  97
  98 ```
  99 [link](http://domain.tld) -->test
 100 ```
 101
 102 > Won't fix because a `)` is a valid part of an URL.