# markdown.ts

`

1const showdown = require(<quote>'showdown'</quote>);

2import { m } from <quote>'hslayout'</quote>;

3

4<comment>/**</comment>

5<comment> * process a markdown comment string and returns the equivalent html syntax. </comment>

6<comment> * @param text the comment to markdown</comment>

7<comment> * @param short if true, only the first paragraph is returned</comment>

8<comment> * @param currentRoute current route, defaults to mithril<quote>'s last route</comment>

9<comment> * @return the marked down comment</comment>

10<comment> */</comment>

11export function markDown(text:string, short:boolean=false, currentRoute:string = m.route.get()):string {

12 const converter = new showdown.Converter({

13 tables: true, <comment>// enables |...| style tables; requires 2nd |---| line</comment>

14<comment></comment> ghCompatibleHeaderId: true, <comment>// github-style dash-separated header IDs</comment>

15<comment></comment> smartIndentationFix: true, <comment>// fixes ES6 template indentations</comment>

16<comment></comment> takslists: true, <comment>// enable - [ ] task; doesn'</quote>t seem to work.</comment>

17<comment></comment> strikethrough: true <comment>// enables ~~text~~</comment>

18<comment></comment> });

19 let result = (!text)? <quote>''</quote> : converter.makeHtml(text);

20 if (short) {

21 const i = result.indexOf(<quote>'

'</quote>);

22 if (i>0) { result = result.substring(0, i); }

23 }

24 result = substituteLinks(result, currentRoute);

25 return result;

26}

27

28<comment>/**</comment>

29<comment> * replaces link statements in the comment with hyperlink references.</comment>

30<comment> * The format of a link statement is <quote>"{@link *docset*:*path* linked text}"</quote>, where</comment>

31<comment> * - *docset* is the name of the docset</comment>

32<comment> * - *path* is the structural path of a component with steps on the path separated by a period,</comment>

33<comment> * following the pattern *module*.*entity*.*member* with</comment>

34<comment> * - *module* = the name of the module file</comment>

35<comment> * - *entity* = [*class* | *function* | *variable*]</comment>

36<comment> * - *member* = [*method* | *variable*]</comment>

37<comment> * - if *path* is omittied, or is `overview`, the library overview will be shown.</comment>

38<comment> * </comment>

39<comment> * Examples: </comment>

40<comment> * - <quote>'{@link hsDocs: Doc Overview}'</quote> -> {@link hsDocs: Doc Overview}</comment>

41<comment> * - <quote>'{@link hsDocs:DocSets.DocSets.add the `adds` function}'</quote> --> {@link hsDocs:DocSets.DocSets.add the `adds` function}</comment>

42<comment> * </comment>

43<comment> * @param comment the comment in which to replace the links</comment>

44<comment> * @param currentRoute the current route - part after #!</comment>

45<comment> * @return the comment with substituted links </comment>

46<comment> */</comment>

47function substituteLinks(comment:string, currentRoute:string):string {

48 <comment>/**</comment>

49<comment> * searches for pattern <quote>'/...'</quote></comment>

50<comment> * @param route </comment>

51<comment> */</comment>

52 function deconstructRoute(route:string) {

53 let lib, mod;

54 route.replace(/\/([^\/.]*)\/([^\/\s]*$)/gi, (match, ...args) => {

55 lib = args[0];

56 mod = args[1];

57 return <quote>''</quote>;

58 });

59 return [lib, mod];

60 }

61

62 function getLibMod(path:string) {

63 let lib, mod, frag;

64 if (path.indexOf(<quote>':'</quote>)>0) {

65 [lib, mod] = path.split(<quote>':'</quote>);

66 } else {

67 lib = defLib;

68 mod = path;

69 }

70 if (mod.indexOf(<quote>'#'</quote>)>0) {

71 [mod, frag] = mod.split(<quote>'#'</quote>);

72 }

73 return [lib, mod, frag];

74 }

75

76 let [defLib] = deconstructRoute(currentRoute);

77

78 <comment>// regex: requires whitespace before {@link; otherwise treated as quoted <quote>'{@link...}'</quote></comment>

79<comment></comment> comment = comment.replace(/\s{@link ([\S]*)\s*([^}]+)}/gi, (match, ...args) => {

80 const path = args[0];

81 const text = args[1];

82 let [lib, module] = getLibMod(path);

83 return (module === <quote>''</quote> || module === <quote>'0'</quote> || module === <quote>'overview'</quote>)?

84 ` <a href=<quote>"#!/api/${lib}/0"</quote>>${text}` :

85 ` <a href=<quote>"#!/api/${lib}/${lib}.${module}"</quote>>${text}`;

86 });

87 return comment;

88}

89

`