The necessity of `-w .` (and `-m False`) isn't properly communicated

[janniklasrose]

Now that #48 is fixed, my Markdown file finally converts without error. I have now noticed that the downloaded/cached images are not being displayed in the generated HTML. Looking at the .html file, the paths all refer to /images/ which I think should be ./images/?

This also applies to v1.17.0 (when using a shorter image name), so was not introduced with the latest fix.

[phseiff]

Have you tried using the -w . option?

gh-md-to-html assumes that you want to host the generated html file on a website, with the current directory being the root of your website. If you want to double-click the html-file, have it open in the browser and have the links work correctly, you need to supply -w ., which essentially tells the script to use relative paths rather than absolute relative paths to reference the cached images.

I also just checked with gh-md-to-html test.md -w ., and it seems to work without problems on my installation. :thinking:

This is also documented here in the documentation, though upon re-reading it, I realize that it is partially misleading in that the first sentence makes it sound less relevant than it is.

[janniklasrose]

I see! I probably should have studied the help a bit more 😅

What you describe makes sense, especially if the purpose of gh_md_to_html is to serve the html as a static site.

The use case that brought me to your code in the first place was to preview GFM files locally before pushing to my repos, so I simply ran with all default arguments: gh-md-to-html file.md. I now see that I should in fact use gh-md-to-html file.md [-w .|-i] -m False (-i to avoid caching, otherwise -w . to be directly double-clickable; -m False to be faithful to GitHub) as is clear from the README. Perhaps it's worth adding a comment in the README for this use case? Or maybe would you consider introducing a more verbose option e.g. --local-preview that implies all these options and essentially exposes the API gh_md_to_html.core_converter.markdown from the command prompt?

[phseiff]

Perhaps it's worth adding a comment in the README for this use case? Or maybe would you consider introducing a more verbose option e.g. --local-preview

Thanks for the suggestion! I actually thought about adding shortcut-options like this to the README, or some additional explanation, but the problem is that the option list as well as the README as a whole are getting increasingly crowded and are in dire need for some re-organizing (simply pasting the help text into the README doesn't really cut it anymore). I already opened and closed several issues regarding this problem; the solution I'll probably end up going with is the one suggested in #47. Including a --local-preview option sounds like a good thing to do once I finished README update, though!

and essentially exposes the API gh_md_to_html.core_converter.markdown from the command prompt?

gh_md_to_html.core_converter.markdown isn't actually called under normal circumstances, unless you use -o OFFLINE or -o OFFLINE+. The standard "core converter" used by the script is gh_md_to_html.markdown_to_html_via_github_api, which you shouldn't use without the whole wrapper that gh_md_to_html forms around it since GitHub's API doesn't fully support special characters in code blocks, has limited support for emoji shortcodes compared to GitHub as a whole and doesn't style the result with CSS (in case you want your files to look like they look on GitHub).

That doesn't invalidate the point you are making, though, of course. :laughing:

Also, if your primary use case is previewing your README files before you push them, you might also be interested in grip, which hosts your README directly in the browser (on localhost) and updates the browser tab whenever you change your README.

If your use case is previewing README files for GitLab, though, you should be aware that GitLab supports some non-GFM features like __TOC__ that aren't supported by grip, but are supported by gh-md-to-html (with an option).