@wider/utils_proto/.jsdoc/tutorials/Using Markdown with ydr_HTMLencode.md

A set of extensions to basic objects giving uniform behaviour in various technical environments

# @wider/utils_proto/proto_string - Using Markdown with wider_HTMLencode

`wider_HTMLencode()` is a general purpose handler of text giving HTML from a string.

`wider_HTMLencode("markdown")` asks that the handler inspects the submitted string and determines the action to be taken.

## Methods of Operation

### Appears to be HTML

If the string appears already to be HTML it is left unchanged

```javascript
const myString = "<li>some text</li>";
myString === myString.wider_HTMLencode("markdown");  // true
```

If you want to receive what looks like HTML code as further HTML marked up - eg to see inside a method's documentation or usage example, then please use `myString.wider_HTMLencode("HTML")` instead.

### Appears to be a markdown document

A markdown document is indicated by it starting with a heading, so the first character needs to be ***#***.  In this case the full markdown interpretation is given as for a complete document, or a complete chapter or section of a document (ie starting with at least one consecutive ***#***))

### Appears to be plain text or inline markdown

If neither of the above apply then the string is checked for the presence of a newline character.  If one is present then the code is treated as notepad-like formatted otherwise it is treated as an inline fragment of a full markdown document

## Driving Markdown

The default settings cause Markdown to deliver true XHTML (as do the other methods of using `.wider_HTMLencode()`). The default settings (**mySettings**) are 

```json
{ "markdown" : {
    "html": true,
    "xhtmlOut": true,
    "breaks": true,
    "linkify" : true
  }
}
```

Before using markdown, it needs to be initialised as soon as the *@wider/utils_proto/proto_string* is imported.  `"".wider_HTMLencode.init()`.  Markdown must be initialised.

You can specify an alternative set by calling the init method before any attempt is made to use this use markdowns `"".wider_HTMLencode.init(mySettings)`.  The settings you provide replace the defaults except that ***html*** and ***xhtmlOut*** cannot be changed.

See [Markdown documentation](https://www.npmjs.com/package/markdown-it) 

You can specify alternative settings on individual calls.   `myString.wider_HTMLencode(mySettings)` - in the same format - and these will apply for that call alone.