Rendering Profiles Settings

Custom Rendering profiles allow you to assign rendering options to IDE scopes to control rendering parameters and options on a per file basis.

You can also select a custom profile to be used as the default profile for the project and for rendering markdown for PDF export.

Default Project Profile

Default project profile is used to set the profile to be used instead of the project markdown settings defined in other settings panes.

ℹ️ Starting with plugin version 2.9.5/2.9.8 the plugin no longer has an issue with some IDE features causing parsing of markdown files always using project rendering profile. All features use scope based profile settings.

⚠️ In plugin versions before 2.9.5/2.9.8 Editor and Preview of markdown files has access to the source file and hence can determine the rendering profile using IDE scopes. Some IDE functionality, like editor gutter icon markers or folding processing for example, creates a lexer/parser without providing the source file or its path, making it impossible to select a rendering profile based on scope. In these cases default project profile will be used. This can create a discrepancy between what is presented by editor/preview elements and elements seen by default project generated rendering profile.

PDF Export Profile

PDF export profile sets the profile used for PDF export. By default it will use COPY_HTML_MIME profile if it is defined or the bundled COPY_HTML_MIME profile.

Plain Text Suggestion Scope

Plain text suggestion search scope defines which files are searched for link and references to present as choices when invoking completions in plain text (ie. no element to provide context for completion choices.). By default it is set to Project Files.

ℹ️ Plain text completions will show the first 1000 completion choices found in files. Providing too many files for the search scope will produce the unexpected side-effect of not showing some links/references because the 1000 choices quota has been filled by previous files. You should define a scope which will limit the search to files where useful links and references are likely to be found both to reduce the amount of time spent in generating the choices and to present useful completions.

Each panel of the custom profile has a "Override Project Settings" check box, if not selected will ignore the custom profile's configuration for this page and use the project's default profile configuration.

Copy Markdown to HTML formatted Text Profile

A custom profile named COPY_HTML_MIME, if present, will be used for rendering HTML for Copy Markdown to HTML formatted text action. If none is defined then internal defaults will be used.

You can use the create COPY_HTML_MIME button to create a profile with a copy of styles used by the default COPY_HTML_MIME so you can customize them to your preferences:

By default Embed Images option in HTML Generation settings is selected and will embed images into the copied HTML text. The Embed Remote Images option can be left unselected so that only local files which will most likely not be resolved when the HTML is pasted, will be embedded into the HTML.

The following constraints apply to this special profile:

• Preview settings are not used.

• Parser, Stylesheet and HTML Generation will allow customization of what HTML formatted text is copied.

• Setting the Embed Images option in HTML Generation tab will convert all image links to embedded data. This will make the HTML self-contained. You can exclude image links with URLs starting with http:// and https:// from being embedded by leaving the Embed Remote Images option not selected.

• Note that the HTML stylesheet is not a standard CSS format file since the HTML element styles are set by the style attribute for each element. The style sheet is a simplified format with each line containing the selector and all the styles for the element. When rendering markdown to HTML, this stylesheet is parsed and the styles contained for each selector are applied to the matching elements.

  Any custom CSS text included in the stylesheet will override the matching selector in the default stylesheet. You only need to include entries which you override.

  All style settings must be contained in a single matching one line entry since they are set in each element and there is no stylesheet. The "css" text is parsed with a simple parser, one line comments stripped out and each line's style attributed to element selector with the style to be added to the element's style attribute.

  The "parent" selector is based on Markdown AST hierarchy and not actual HTML, so any HTML tags surrounding Markdown elements will have no effect. The classes are hardcoded into the attribute provider such as: tr.odd, tr.even and li.loose, all based on Markdown AST.

Export Rendered Markdown to PDF Profile

The plugin uses Open HTML to PDF software library https://openhtmltopdf.com to customize the PDF rendering you need to either create your own CSS and add to the rendering profile in "Stylesheet" settings or to take the default CSS used by the plugin and adapt it to your purpose.

By default Export to PDF action will use the COPY_HTML_MIME profile unless a PDF export profile is defined.

Setting the Embed Images option in HTML Generation settings will embed images into the HTML text used for exporting the PDF. The Embed Remote Images option can be left unselected so that only local files which will most likely not be resolved when the HTML is converted, will be embedded into the HTML.

The layout sets font size in pixels in the .markdown-body and .wiki-body class selectors. The rest use em units to set relative size. So to just change the font size you can add the following to Apply custom CSS text in stylesheet settings to the PDF profile you setup:

.markdown-body,
.wiki-body {
    overflow: hidden;
    word-wrap: break-word;
    font-size: 10px;
}

Default font size for JavaFX stylesheet is 14px.

If using a custom rendering profile for PDF export you will need to take into consideration Open HTML To PDF limitations in parsing the resulting CSS attributes.

Configuring for Non-Latin Character Sets

Bundled fonts in the OpenHtmlToPDF library support only basic latin unicode characters. For other character sets the plugin includes Google Noto Serif/Sans/Mono fonts with regular/bold/italic/bold-italic variations. The default JavaFX style sheet defines noto-serif, noto-sans and noto-mono font families so these can be added to custom CSS text and will allow PDF export to render characters in these fonts.

You can use the create PDF Export Profile button to create a profile configured for PDF exporting which you can customize if needed:

Then select this profile for PDF Export:

If CJK character sets are not required then the default PDF Export profile can be used without modification.

Configuring for CJK Character Sets

The OpenHtmlToPDF library requires TrueType fonts and Noto CJK fonts are OpenType which cannot be used. The solution is to download a TrueType Unicode font that supports CJK character set and add it to the custom rendering profile to be used for PDF. (OpenHtmlToPDF font instruction https://github.com/danfickle/openhtmltopdf/wiki/Fonts)

For example adding: arialuni.ttf from https://www.wfonts.com/font/arial-unicode-ms will add CJK character sets supported by that font.

By changing Stylesheet custom CSS Text will result in PDF export which will handle all character sets available in Noto and arialuni fonts.

ℹ️ Change the file:///... URL to the font download/installation directory on your system. On Windows the URL should start with file:/X:/... where X:/... is the drive letter and full path of the font location, with \ replaced by /.

@font-face {
  font-family: 'noto-cjk';
  src: url('file:///Users/vlad/src/fonts/arialuni.ttf');
  font-weight: normal;
  font-style: normal;
}

.markdown-body,
.wiki-body {
    font-family: 'noto-sans', 'noto-cjk', Arial, "Helvetica Neue", "Segoe UI", freesans, sans-serif;
    font-size: 16px;
    line-height: 1.6;
}

var,
code,
kbd,
pre {
    font: 0.9em 'noto-mono', Consolas, Inconsolata, Courier, monospace;
}