Create a single cross platform help file from existing markdown file

Question

I'm working on an existing project that already has a markdown file describing the functionality and any relevant info.
I'd like to create a single help file that can be viewed on different platforms windows/os/linux.
For the time beeing I've converted the markdown file into an html one and then zipped the index.html with images folder into one zip file.
However I'd like to have if possible one single help file that is directly viewed without the need of extracting it.

So far I've rejected the following solutions for specific reasons:

1. MHTML and may encounter problems with different browsers in different platforms and there is the need for addons
2. CHM is generally a windows based format.
3. Whichever conversion I tried from markdown to pdf (phantomjs , pandoc) had not satisfying results to the point that the pdf file if chosen should be created from scratch which I'd like to avoid.

So I'd like to ask whether there is a way to achieve the production of a cross-platform single help file or should I stick to the zip solution?

Answer 1

I had the same problem than yours, and I finally use a solution to giving me only one HTML file in output.

I write my Markdown content with Sublime Text and I use this extension for building Markdown into HTML documents :

Sublime Text Markdown Preview

It permits me to generate a single HTML file, with embed CSS (it give me a GitHub like markdown rendering) and with embed image (using base64 encoding).

You can add your specific CSS stylesheet if you want to and there is a lot of avalaible customizations.

This is how I configure the plugin :

{
    "browser": "default",
    "parser": "markdown",
    "build_action": "build",
    "enable_mathjax": true,
    "enable_uml": true,
    "enable_highlight": true,
    "enable_pygments": true,
    "guess_language": true,
    "enabled_extensions": "default",
    "enabled_parsers": ["github", "markdown" ],
    "markdown_binary_map": {
        "multimarkdown": ["/usr/local/bin/multimarkdown"]
    },
    "github_mode": "markdown",
    "github_inject_header_ids": false,
    "css": ["default"],
    "allow_css_overrides": true,
    "enable_autoreload": true,
    "markdown_filetypes": [".md", ".markdown", ".mdown"],
    "html_simple": false,
    "image_path_conversion": "base64",
    "file_path_conversions": "absolute",
    "strip_critic_marks": "none",
    "strip_yaml_front_matter": false,
    "show_panel_on_build": true,
    "embed_css_for_sublime_output": true
}

I know this is an answer very specific about the text editor, but I hope that it could help.