
Show HN: Markdown page – Create a web page with just markdown - oscargeorge
https://github.com/oscarmorrison/md-page
======
themodelplumber
Props for the simplicity in getting something published. That's really cool.

Along similar lines, I went back to LibreOffice recently and made a few web
pages with it, just to try it out. It worked better than I expected.

After adding a simple PHP controller to the mix, injecting some CSS for
responsiveness and other tags as needed, I have been impressed with how easy
it makes publishing. If a single-pager is what's needed (or multi-pagers
perhaps; I just haven't tried it yet), if what matters most is getting links
and information public, it's a useful tool.

------
rubyn00bie
This is kind of neat but why not just use pandoc?

pandoc -s input.md -t html -o output.html

[https://pandoc.org/](https://pandoc.org/)

~~~
Aelius
Why would you want to constantly recompile documents every time you make an
edit to them? Why would you want to juggle two files for every document you
produce?

~~~
kryptk
For what it's worth, this is the problem GitLab Pages solves. A simple "git
push" to a properly to figured repo will rebuild and redeploy your static
site, the actual html output doesnt go into the repo.

~~~
askmike
This is for people who don't want to setup and manage a deployment pipeline
hooked up to a git source code repo.

------
oscargeorge
Thanks everyone for taking the time to look, and give some feedback. Most
definitely better options out there, but I was really aiming for simple, and
low tech knowledge to get a md page on the internet.

I added a wiki page [https://github.com/oscarmorrison/md-
page/wiki](https://github.com/oscarmorrison/md-page/wiki) explaining a couple
of use cases, and some more details. Feel free to leave more feedback / open
issues. Thanks Oscar!

------
gprasanth
There has been Strapdownjs[1] around for quite a while now. It's simple,
supports some theming as well. Anyway, good luck with this. Always fun to
build something from scratch.

[1] - [http://strapdownjs.com/](http://strapdownjs.com/)

~~~
kyledrake
This is more evidence to me that <xmp> needs to not go away, I know browsers
are considering it and I really hope they don't go that route.

I use <xmp> for html code commenting - see the source code at
[https://elementcss.neocities.org/](https://elementcss.neocities.org/)

The one thing these markdown examples are missing is a way to do grids! I bet
there's a clever way to make columns and rows work.

------
posamari
I like it a lot, both concept and execution. Little nitpicking:

> Create a webpage by just writing markdown, nothing else!

The „nothing else” bit looks inaccurate, there’s a script tag at the very
beginning.

~~~
boffinism
Nitpicking more: raw html (including script tags) is valid markdown! So it
technically is markdown and nothing else.

~~~
posamari
Noted! Then again, super nitpicking, if that script tag in the beginning is
part of the markdown document, then it should also be displayed in the final
document.

------
littlecranky67
Throwing in to the list of alternatives to this:
[http://mdwiki.info](http://mdwiki.info) which actually does not even require
you to create a .html file, but just plain .md files and a standard/template
version of mdwiki as index.html.

Disclaimer: I am the author of it, and it is nowadays unmaintained.

~~~
Evidlo
Why did you archive the repo?

------
majewsky
A neat party trick, but what actual use-case is there that isn't better served
by server-side Markdown to HTML conversion?

~~~
toomim
Here are three use-cases:

1\. You are editing documents locally on your computer. This lets you double-
click to view nice markdown in a web browser with a `file://` url.

2\. You are editing a website, but don't have control over the server-side
code.

3\. You don't want to install a markdown rendering library on the server.

~~~
majewsky
> You are editing a website, but don't have control over the server-side code.

You don't have control over the server-side code, but it will let you inject
<script> tags into the content? That seems a bit weird.

~~~
slimsag
GitHub pages is literally like this, no?

~~~
majewsky
You're right, though GHP is a bad example since it includes a Markdown
renderer.

------
bloopernova
I really like this, thank you for writing and sharing it!

I take notes and write personal documentation in Markdown for tickets and
projects. Nowadays I usually write in Visual Studio Code or Vim. I can see
myself using this to share pages with people. Although I wonder how my syntax
highlighting will work - I guess I'll have to write a shell script to copy the
.md file to .html and insert the call to the md-page.js at the top.

------
jonathonf
I think this has already been done by Jr [1].

And for other markup languages, e.g. Dr [2] for AsciiDoc.

[1] [https://github.com/Xeoncross/jr](https://github.com/Xeoncross/jr) [2]
[https://github.com/jonathonf/Dr](https://github.com/jonathonf/Dr)

------
enriquto
Honestly, I prefer writing directly plain html5 with implicit tags. I cannot
see any advantage of markdown over html for this particular usage.

~~~
dredmorbius
Markdown doesn't require tag closure, and eliminates the <p> tag entirely.
This makes for a cleaner and faster composing experience.

I did little but wruite in HTML from the late 1990s to mid 2010s. Markdown is
my preferred route now.

Also conversant in LaTeX, formerly; nroff, DocBook, WP4.2, Wordstar (both with
'reveal codes' capabilities), and probably more. Pandoc is a game-changer.

~~~
enriquto
> Markdown doesn't require tag closure, and eliminates the <p> tag entirely.
> This makes for a cleaner and faster composing experience.

The HTML5 specification also allows omitting most closing tags (except for the
obvious ones, that you also need to close in markdown).

You are right about the <p> tag, still. It is the main source of annoyance
when writing long documents in html by hand.

~~~
dredmorbius
_Well-formed_ HTML5 needs closure though, no? Hrm ... ok, looks like specs are
_far_ looser than I'd thought.

h[1-6], li, blockquote, pre, can all be specified via an opening-only syntax.

p, ul, ol, and dl can be omitted entirely.

Arguably anchors require closure, but the syntax is still briefer than HTML.
Images likewise.

Header, footer, and aside don't exist (they can be supplied in a template).
article, div, and span are also ignored.

Italic, bold, strikeout, code, subscript, and superscript require a
lightweight closure, and are actually the main cause of grief in my Markup
writing.

Tables are hugely more sane.

And footnotes automajickally exist. _Swoon!_

It's not that HTML is foreign or annoying to me. It's just .... more
_frictional_.

And I have all kinds of nice words to say for HTML5. The base spec _is_ quite
good.

------
jchw
The flicker when loading the page sucks. I guess displaying Markdown in case
of failure is not the worst thing, but it would be nice if there was a
possible way to allow getting rid of the flicker at the cost of not having a
graceful fallback.

One way you could accomplish this is by supporting script tags for this, like
wrapping the page in:

    
    
        <script type="text/markdown">...</script>
    

...as an optional way to use the library. Browsers won't (shouldn't?) try to
render the contents of the script tag before you get to it, so it would act
like a typical SPA.

~~~
judofyr
Yesss, finally a use-case for the `<noframes>`-hack! This is actually even
better than the approach of OP since we're guaranteed to get a plain text
representation of the text (instead of the browser parsing it as HTML).

example.html:

    
    
        <script src="mdpage.js"></script><noframes>
    
        # Header
        Welcome to my simplest site
    
        - A
        - awesome
        - list
    

mdpage.js:

    
    
        document.write("<div id=main></div>");
    
        document.addEventListener("DOMContentLoaded", function() {
          var script = document.createElement('script');
          script.src = "https://unpkg.com/showdown";
          document.head.appendChild(script);
    
          var noframes = document.querySelector('noframes');
    
          script.onload = function() {
            var converter = new showdown.Converter({
              emoji: true,
              underline: true,
            })
            converter.setFlavor('github')
            main.innerHTML = converter.makeHtml(noframes.textContent)
          };
        });

~~~
oscargeorge
Thanks @judofyr + @matt-tingen. I just updated it to use the 'noscript'
opening tag. Good idea, and solved my normal html not working problem! Thanks
a bunch!

------
watchdogtimer
I wonder what effect having a page solely in markdown has on SEO? Without
markup for headers, links, etc, how will search engines prioritize content?
Will they use the raw content or the parsed HTML?

~~~
bitofhope
I'd imagine anyone particularly concerned with SEO would be likely to prefer a
more fully-featured method of content management anyway.

~~~
bunnycorn
One of the problems of the modern web.

Sure we can add JavaScript and make the web work the way we want, like this
example, but many more... but what about SEO?

For example, I had a page for my app, it was very minimalistic and pretty, I
targeted the 400 msec cold loading time, instead of a screenshot, I had a very
well encoded h.265 screen recording (it's okay, people who can run the app,
can certainly see the video), that video didn't cost more than a well
optimized JPEG.

But I had to drop the video, and only load it after the JPEG loaded because of
SEO reasons. Google isn't smart enough to recognize the video unless it's a
YouTube video.

------
das_keyboard
I looked for something exactly like this a while ago. Thank you very much for
posting this.

------
hachibu
Awesome, nice work! I like the simple usage of just adding a script tag to the
top. I also experimented with this idea[1].

[1] - [https://github.com/hachibu/md_spa](https://github.com/hachibu/md_spa)

------
eeZah7Ux
[http://oscarmorrison.com/md-page/](http://oscarmorrison.com/md-page/) shows
only a blank page on firefox.

I even disabled NoScript for the site. Thanks, I'd rather have plain HTML.

~~~
oscargeorge
Just tested in on FF 62. Seems fine. But yeah I have really only tested it on
chrome

------
dplgk
Sorry to sound cynical but this 10-15 minutes of work?

~~~
graylien
time well spent

------
Kagerjay
So how does this work exactly?

It looks like you wrote a script.js file, which calls showdown.js library
(converting markdown to html). A uglified version called `md-page` is made
pulling both resources

Basically, the script does following

1) wait for page to load

2) add css-styles via javascript

3) shove all the markdown in a variable "markdown", passing it as one giant
string

4) Add settings for showdown.js

5) Rewrite entire markdown on page to HTML via showdown.js

6) Append to body and render

I could fork it and add breakpoints / run debugger but this is what I got from
looking at source code

~~~
oscargeorge
yep. you're 100% on the money. no wizardry here. Couple of extra features like
ability to hash link, and external url open in new window. but that it

~~~
Kagerjay
[https://github.com/oscarmorrison/md-
page/blob/master/script....](https://github.com/oscarmorrison/md-
page/blob/master/script.js)

Line 43 to 48, I am not entirely sure what that hashlink does. What is the
setTimeout function for? Could you expand on that?

~~~
oscargeorge
It's to make linking to headers work. Eg oscarmorridon.com/md-page#code

As the element doesn't exist at time of first load this is a work around to
focus on id once content is rendered in html

~~~
oscargeorge
* [https://oscarmorrison.com/md-page/#code](https://oscarmorrison.com/md-page/#code)

------
Crontab
Interesting. Out of curiosity, does anyone know if is there a webserver that
natively converts Markdown to HTML?

~~~
detroitenglish
Caddy server has this feature baked in:
[https://caddyserver.com/docs/markdown](https://caddyserver.com/docs/markdown)

------
FraaJad
[Markdeep]([https://casual-
effects.com/markdeep/features.md.html](https://casual-
effects.com/markdeep/features.md.html)) has waaay more features than this.

~~~
arkades
So does HTML/CSS+JS. A project aiming at simplicity probably isn't one to
criticize for lack of features.

~~~
FraaJad
the mechanism for using both the projects is the same -- include a JS file. If
the effort to use both is the same, why would I not use the one that has more
features?

~~~
elcomet
Maybe he doesn't need the features, or maybe it is slower

------
major505
That will be usefull. Nice work.

------
walterbell
Why can't web browsers render basic markdown natively (no plugins)? Wouldn't
that be a much simpler and more secure parser than HTML?

A _Markdown Web_ would look like the early Web.

~~~
waivek
[https://tools.ietf.org/html/rfc7763](https://tools.ietf.org/html/rfc7763)

~~~
walterbell
Thank you!

------
sandGorgon
static site frameworks like jekyll, hugo and gatsbyjs support this.

gatsbyjs supports md, yaml and external graphql

------
wetpaws
Is it me or you folks just invented HTML?

