Markdown to HTML: things to amend

Use the correct and current DOCTYPE

When DT converts (renders) Markdown to HTML, it adds a DOCTYPE at the top of the HTML (which is required). However, this DOCTYPE is completely outdated (and I’m not sure it is even valid). Nowadays, the statement should simply be
<!DOCTYPE html> and not <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" ""> HTML4.0 became a standard in 1999, and since 2014 HTML 5 is the (only) official standard.

Using an outdated DOCTYPE puts browsers in quirks mode, which in turn makes using current standards in the document haphazard.

Make user-defined CSS work consistently

DT offers three possibilities to define styles for MD to HTML conversion:

  • Via a stylesheet setting in Preferences/Data/Markdown. This stylesheet can be located either in one of the databases or in the filesystem.
  • By specifying a stylesheet with a link element at the top of the MD file. Again, the stylesheet can be located in one of the databases or in the filesystem.
  • By adding the styles verbatim in a <style> element at the top of the file.

Unfortunately (and unexpectedly!), these three methods lead to different results. The first one overrides DT’s stylesheet completely, whereas the other two change only those pre-defined DT styles they’re explicitly defining. On the other hand, defining a global stylesheet in the preferences is exactly what one wants to do (as opposed to adding the stuff to each and every MD file by hand).

The behaviour of the globally defined stylesheet (in the preferences) goes completely against the idea of CSS: The C stands for cascading (not for replacing). Its contents should be added to the rendered HTML after all internal DT styles, not instead of them.

Explanation: Let’s assume that I like DT’s styling of HTML, but I want my tables left aligned (whereas DT centers them). Intuitively, I’d put table { margin: 1em} in my global stylesheet. By doing so, I’ll put the table to the left of the document, but I’ll loose all default styling of it (like alternating row colors). If I put the exact same statement in a \<style> element at the top of my MD document, the table will be output at the left and retain its default styling.

1 Like

On the other hand, defining a global stylesheet in the preferences is exactly what one wants to do (as opposed to adding the stuff to each and every MD file by hand).

I’m not sure if this is worded in a particular way but if it’s written as intended, it’s subjective and not the case for all people. Not everyone wants to use a global stylesheet. It depends on the individual and their situation.

Ok, what I meant was:

If a user wants their documents styled in the same way, they’d want to do that in a single place, ie the preferences. As opposed to adding the link or script element to every document separately.

Does that make it clearer?

Indeed, much clearer, especially to Markdown noobs I’d think.

That is absolutely intentional to easily replace the internal default style sheet whereas the other methods just extend the Markdown document and therefore the HTML source.

E.g. imagine the internal style sheet wouldn’t be replaced but used in addition to the global stylesheet specified by the user (e.g. a typical Markdown style sheet found on the internet). I’m sure the layout will be most likely very artistic :slight_smile: Meaning that the global preference is the only possibility to get rid of the internal stylesheet .

It seems that there are two scenarios. One: a user wants to change only some part of the default style sheet, e.g. place the tables flush left instead of centred. Two: a user wants to have a complete, wonderful, style sheet to make sure their HTML looks exactly and in every single details as they want it.

I do not quite understand why inserting the user stylesheet after the default one would be harmful in any of these two cases. In the first one, only those styles explicitly modified by the user are changed, the rest remains at the default. In the second case the stylesheet has to be “complete” (in the sense of specifying every detail) anyway. If it wouldn’t, the resulting HTML would not look exactly as the user wanted, e.g. in a browser that enforces its own styles.

To emphasize: Its a cascade. The default (DT’s or the browser’s) comes first. Then any style that explicitly overrides the default. And the current situation is just confusing, because it does not permit users to simply override only part of the default. Nor is it possible to get at the default style sheet easily (it seems that only those styles are included in the HTML that are used by the document - purging?).

A practical solution might be a check box to the right of the global setting, permitting to select between “override” or “augment”.

Funny how years go by when you’re busy :slight_smile: Updated.

1 Like