diff --git a/README.md b/README.md index 5da7135..9aaeb4b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Markdown plug-in + # TeXmacs markdown plugin This plugin is a (for now one-way) converter to markdown format for @@ -10,8 +12,9 @@ and pasting into the markdown file. The plugin has been developed for its use in two specific websites, [Paperwhy](https://paperwhy.8027.org/) and appliedAI's [TransferLab](https://transferlab.appliedai.de/), and can use multiple -extensions specific to the static website generator [Hugo](https://gohugo.io/). -There might still be some code very specific to those sites, YMMV. +extensions specific to the static website generator +[Hugo](https://gohugo.io/). There might still be some code very specific to +those sites, YMMV. ## Setup @@ -30,6 +33,18 @@ For Windows, the path (usually?) is You can activate a menu with `Tools -> Markdown plugin`. +## Extensions to vanilla markdown + +Besides standard Markdown, this plugins does the following: + +* Footnotes (and marginal notes, exported as footnotes for vanilla markdown). +* Links to equations and equation arrays. Labels are exported as HTML + `` with identifiers sanitized and custom CSS. See + `extensions/tmmarkdown.css`. +* Support for most standard environments, both numbered and unnumbered. + Localized and with support for references and ``. +* Probably more… + ## Hugo support In addition to standard markdown, almost everything that Hugo supports can be @@ -40,55 +55,45 @@ Setting values for the frontmatter is suported via a dedicated macro defined in `hugo.ts`. To use it first insert the `Markdown -> Hugo` package in `Document -> Style -> Add package` or using the plus sign in the focus bar. -Now you can type `\hugo-front` and input any number of key|value pairs as -arguments, one argument each. That is: type `\hugo-front`, then use structured -insert right to add two arguments and use the first for the key and the second -for the value. Repeat as needed. Currently, only strings, lists of strings and -dates (insert with `\date`) are supported as values. To enter a list, input -`\tuple` as the value and use structured insert right to add items. +Now you can use `` to input any number of `key|value` pairs as +arguments, one argument each. That is: insert the tag ``, then use +structured insert right to add two arguments and use the first for the key and +the second for the value. Repeat as needed. It is possible to use strings, +booleans (“true”, “false”) or dates (insert with ``). Additionally, the +macro `` inserts the name of the file with `.pdf` appended. To enter +a list, input `` as the value and use structured insert right to add +items. To input a dictionary, use `` and again use structured insert to +create tuples of `key|value`. ### Supported shortcodes -Some of the texmacs markdown requires custom shortcodes and layouts. You can -find them in `extensions/hugo`. Just copy the partials and shortcodes to your -Hugo project. - - * Figures are converted to `{{< tmfigure … >}}`. This is a simplified version - of Hugo's `{{
}}`, which can have `.Inner` content. This is required - e.g. to have citations in captions or arbitrary markup. - * To introduce any shortcode in a TeXmacs document, you can use the macro - `\hugo-short`. - * Citations are automatically detected and converted to - `{{< cite ref1 ref2 ... >}}`, and all of them are gathered in the frontmatter - as well, for indization by Hugo's taxonomy system. The presentation of the - label itself is done using CSS. Include the partial `ref_labels.html.html` - in the document `` for that. - * Bibliography is rendered with the `references.html.html` template. +All custom shortcodes are in `extensions/hugo/`. + +* Figures are converted to `{{< figure … >}}`. +* For arbitrary shortcodes, use ``, e.g. `` for + `{{< toc >}}`. +* Citations are automatically detected and converted to `{{< cite ref + >}}`, and all of them are gathered in the frontmatter as well, for + indization by Hugo's taxonomy system. The rendering of bibliography is done + by `{{< references >}}`. +* Marginal notes and figures are converted to `{{< sidenote … >}}` + and `{{< sidefigure … >}}`. # Known issues - * The converter can break with malformed or unexpected input, like markup - inside tags whose values should be strings, although some cases are (a bit - sloppily) handled. - * Error reporting is rather lacking. Run TeXmacs in a console to see stack +For an up-to date list, see the [issue tracker in +GitHub](https://github.com/texmacs/markdown/issues/). + +* The converter can break with malformed or unexpected input, like markup + inside tags whose values should be strings (although many cases are + “handled”) +* Error reporting is rather lacking. Run TeXmacs in a console to see stack traces and such in case you are running into problems. - * No tables (yet)! - * Images must be linked, not embedded in the document. - -# To do - - * Reverse markdown to TeXmacs conversion. - * Declare converter options in init file, and use. - * Make behaviour of all tags configurable, e.g. to support different styles. - For instance, should titles, chapters or sections be `h1`? - * Extract all Hugo extensions to a separate file, use overloading and - extension of the dispatch hashmaps. - * Use “converter environments”? - * Use TeXmacs' `logic-dispatch`? - * line-breaks and other markup in doc-data (e.g. in the doc-title) need to be - properly handled if included in YAML metadata for Hugo. - * Support for tables. - * Extract embedded images. +* EPS and PDF images are not supported by browsers. As a workaround allowing + to have both, use ``. The first argument is for TeXmacs and + the second one for the markdown export. +* The converter supports only one style. For instance all environments have + emphasized bodies and bold names, `
` is exported as `h1`, etc. # License diff --git a/doc/markdown.en.tm b/doc/markdown.en.tm index 4742df0..3c23cda 100644 --- a/doc/markdown.en.tm +++ b/doc/markdown.en.tm @@ -1,4 +1,4 @@ - + @@ -39,6 +39,25 @@ You can activate a menu with . + + + Besides standard Markdown, this plugins does the following: + + <\itemize-dot> + Footnotes (and marginal notes, exported as footnotes for vanilla + markdown). + + Links to equations and equation arrays. Labels are exported as HTML + span\> with identifiers sanitized and custom CSS. + See . + + Support for most standard environments, both numbered and + unnumbered. Localized and with support for references and + . + + Probably more + + In addition to standard markdown, almost everything that Hugo supports can @@ -50,32 +69,45 @@ package in or using the plus sign in the focus bar. - Now you can type and input any number of key\|value - pairs as arguments, one argument each. That is: type - , then use structured insert right to add two - arguments and use the first for the key and the second for the value. - Repeat as needed. Currently, only strings, lists of strings and dates - (insert with ) are supported as values. To enter a list, - input as the value and use structured insert right to - add items. + Now you can use to input any number of + pairs as arguments, one argument each. That is: + insert the tag , then use structured insert right + to add two arguments and use the first for the key and the second for the + value. Repeat as needed. It is possible to use strings, booleans (\Ptrue\Q, + \Pfalse\Q) or dates (insert with ). Additionally, the + macro inserts the name of the file with + appended. To enter a list, input as + the value and use structured insert right to add items. To input a + dictionary, use and again use structured insert to + create tuples of . + All custom shortcodes are in . + <\itemize-dot> Figures are converted to figure - \}}> + \}}>. - For arbitrary shortcodes, use . + For arbitrary shortcodes, use , e.g. + for toc \}}>. Citations are automatically detected and converted to cite ref \}}>, and all of them are gathered in - the frontmatter as well, for indization by Hugo's taxonomy system. + the frontmatter as well, for indization by Hugo's taxonomy system. The + rendering of bibliography is done by references + \}}>. - Probably more + Marginal notes and figures are converted to + sidenote \}}> and sidefigure + \}}>. + For an up-to date list, see the . + <\itemize> The converter can break with malformed or unexpected input, like markup inside tags whose values should be strings (although many cases @@ -84,34 +116,13 @@ Error reporting is rather lacking. Run in a console to see stack traces and such in case you are running into problems. - No tables (yet)! - - Images must be linked, not embedded in the document. - - - - - <\itemize> - Reverse markdown to conversion. - - Declare converter options in init file, and use. - - Make behaviour of all tags configurable, e.g. to support different - styles. For instance, should titles, chapters or sections be ? - - Extract all Hugo extensions to a separate file, use overloading and - extension of the dispatch hashmaps. - - Use \Pconverter environments\Q? - - Use ' ? - - line-breaks and other markup in doc-data (e.g. in the doc-title) - need to be properly handled if included in YAML metadata for Hugo. - - Support for tables. + EPS and PDF images are not supported by browsers. As a workaround + allowing to have both, use . The first + argument is for and the second one for the markdown export. - Extract embedded images. + The converter supports only one style. For instance all + environments have emphasized bodies and bold names, + is exported as , etc.