search

tomjoht / documentation-theme-jekyll

A Jekyll-based theme designed for documentation and help systems. See the link for detailed instructions on setting up and configuring everything.
http://idratherbewriting.com/documentation-theme-jekyll/
Other
1.18k stars 1.19k forks source link

.md vs. .html for content ? #93

Closed ghost closed 7 years ago

ghost commented 7 years ago

It's unclear to me when I should create a .html file and when I should create a .md file, within the context of this theme.

Looking at the sample implementation (the documentation for this theme), for two of the "products", product1 and product2, there's a p*_landing_page.html file in the product's dir/folder, along with lots of .md files. For the "default" (home) mydoc product, its "main" page, which is the Home page for the entire site, is index.md, and all the files that are under the mydoc dir/folder are .md.

It doesn't seem to matter whether one creates a .html vs. .md file; both seem to be usable in *_sidebar.yml files.

So is it simply a matter of whether one wants to have html or markdown code in that page?

tomjoht commented 7 years ago

Jekyll transforms .md to .html when you build the site. If your file is primarily HTML, as is the case with the landing pages, there's not a strong need to use Markdown. Markdown creates its own issues with HTML, since element bookends need to be flush left.

ghost commented 7 years ago

Yes, the md->html transformation was clear. And it sounds like the "source content" can be in either format, with html somewhat preferred unless, of course, markdown is easier for the given content. Thanks for clarifying!

ghost commented 7 years ago

I'm closing this (non) issue because I've no further related questions.