Search code examples
markdownjekyllgithub-pagesprose

Static site with inline markdown, without Jekyll (or templating engine) -- can it be done?

Github Pages, Jekyll, Prose.io. These things all seem to be created to play very nice with each other.

I'm aware of Jekyll, which utilizes Markdown content to make "blog aware" static pages, yada yada. The thing is, I don't really want all of Jekyll's functionality, but I do want to utilize Github Pages to host static sites. And I do want a more user friendly way of editing content on the site than HTML.

All I want to know is if there is a way I can take a .md file generated by Prose (which pushes the content to your Github Pages repo), and place it in some sort of .md include in say, the "#aboutMe" div of my index.html file.

If I can't do this without Jekyll, is there a less functional templating engine that I can sprinkle on top of my site without it needing to generate the whole thing? Would an alternative be feasible when being used with Github pages?

Furthermore, if there isn't some sort of templating alternative, is there an alternative to Prose which converts the MD content to HTML upon pushing to Github so I could then include those "content" files in my page with JS? I would need it then pull out these same files for editing in MD if they were to need content changes. As far as I can tell, you can only publish .md files with Prose. I don't want to have to preprocess the HTML locally first - I'd like to just push the .md files to github and have it work. Is this real?

Solution

  • As already suggested in a comment before, Jekyll + GitHub Pages does all you need.

    It also does a lot more, but you don't need to use any of it.

    You can set up a simple Jekyll site on GitHub Pages, consisting just of:

    • a single layout file (with some kind of dynamic navigation which auto-updates when you add a new page, by looping through site.pages)
    • multiple pages, consisting of .md files which use that layout file

    After that, you never touch the layout file's HTML again.
    You just write Markdown into the .md files, commit these in Git and push to GitHub (you can even edit them in GitHub's web UI, without using Git or your local machine directly at all).

    GitHub Pages will then build your site.
    Granted, your site does need to be built, but GitHub will do this for you. You don't need to create/preprocess anything on your local machine.