In the beginning was RUNOFF from MIT, which originally had about the power of Markdown. More features were added, and it became nroff, then troff, the ditrofff, and macro systems were added on top of it. It became too hard to use for casual work.
Then there was TeX, which was a saner approach to what troff did. Macro systems were added on top of it. It became too hard to use for casual work.
Then there was HTML, which started out with about the power of Markdown. More features were added. It became too hard to use for casual work.
Then there was BBcode, which started out with about the power of original HTML. It didn't gain many features, and is still widely used.
Then there was Markdown, which started out with about the power of original HTML. More features were added. Macros have been added by at least five people, but haven't quite gone mainstream yet. When Markdown gets macros, it, too, will be too hard to use for casual work.
The nice thing about Markdown that doesn't apply to those other formats is that it's designed to read naturally in plaintext. That constraint should (in theory) prevent it from transforming into something prohibitively complicated to write in.
> Except for links to images. I can never freaking remember those.
They work like standard Markdown links (text in square brackets, followed by link in parens), except you add a bang in front of it. The bang looks like an upside-down "i", the first letter of "image".
Edit: read too fast; _links_ to images use image instead of text in a link, so you just replace the text with text in square brackets with the syntax of Markdown image. I've never struggled too much with this one, so I don't have any useful mnemonics, sorry.
That's why significant end of line whitespace is a terrible design feature. You can't see it. It might get deleted accidentally.
There were some systems back in the DOS/early UNIX era which had significant EOL whitespace. Spaces at the end of a line are still significant following a "\" in shell files. Some early word processors under DOS had significant whitespace at EOL, but tended to display something like a paragraph mark when it mattered.
Python had tab/space trouble at beginnings of lines, but the compiler was finally fixed so that it emits an error if tabs and spaces are mixed in a way which makes indentation visually ambiguous. That was a neat solution to the problem.
Leading tabs in makefiles were a mistake. The author of "make" once wrote that he put that in, and then, the next day, realized it was a bad idea. But he already had a user base of three users and didn't want to change it and break their code.
I thought this idea was dead and buried. Sometimes, they come back.
For what it's worth, GitHub Flavored Markdown changes this to be more TeXy: any newline in text renders as a <br>, and you add an extra blank line to denote a paragraph break.
Unfortunately that means that you absolutely need to enable word wrap in your editor, people cat-ing your readme on the shell will see ugly mid-word wraps, etc. Not the end of the world or anything, but somewhat inconvenient.
That sounds like a failure of cat more than a failure of markdown. There isn't a command-line argument for cat to break long-lines at the last whitespace of the line instead of mid-word?
Intriguing: significant white space on the right-hand side. At least you can see the significant whitespace in Python.
I also have my editor configured to strip trailing whitespace but also to highlight it. People can be very sloppy leaving (insignificant) whitspace lying around in code.
I always forget the combination of an image with a link and alt text. [![click here)[lol.com/img.png] or something like that, the only other thing that annoys me is when people use underscoring / equals under text to make it a heading rather than #s, otherwise I find markdown a pleasure to write in.
That's why I prefer ReST. More powerful syntax out of the box with a standard extension scheme so you don't end up with the mess of all the different incompatible Markdown implementations. With the internal structure exposed as an XML format (rst2xml) it is easy to transform documentation into a wide variety of formats that docutils or Sphinx don't handle directly.
The XML dump exposes the parsed document structure so you aren't forced to use the usually limited output options of the native ReST or Markdown tools. Instead of generating the lackluster output from latexpdf you can transform from ReST -> Docbook -> XSL-FO -> PDF, or other targets like HTML, WordML, DocX, or ODF. Manipulating documents is what XML is really for. It gets a bad rap because it is abused so much for storing data, scripting, and other silly stuff.
I once contracted at a company where one of the salaried staff was tasked with implementing Markdown. For some reason, he actually implemented BBCode (I think with a regex he'd found online somewhere). When I tried to explain to him that BBCode and Markdown were, you know, quite different, he got angry with me and started shouting that "Markdown has no standard, so it can be anything you want!"
I left the conversation at that point because I sensed it might turn ugly (it was the afternoon, and he had a penchant for boozy lunches when his boss was out of the office).
That's basically a sample size of n=5 from which you inferred that "has macros" and "is popular" are causally linked, which should get you expelled from every statistics department in the world ;)
My guess is that various syntaxes for doing basically the same thing fade in and out of popularity randomly and for the most part independent of their feature set, just as different ways of covering the body with cloth fade in and out of popularity. Last year's collection isn't unpopular because it became to hard to use, people want new stuff and they don't want to be associated with old stuff.
No, no, I don't claim that having macros is required for popularity. I claim only that the growth pattern of "simple" markup languages is to add features which make them no longer simple. At that point, new simpler markup languages appear, and the cycle repeats.
Texinfo has actually not been so bad to use, though ugly as sin. Scribble / Skribilo (racket & guile) are both excellent, but have some sharp edges. At least for HTML I've found that using a basic subset still hasn't broken.
I use org-mode pretty exclusively, but it has the opposite problem of what you mention - it requires macros in your editor (maybe a set of Editor MACroS if you will..). This makes in unusable for anyone outside the emacs lifestyle.
Markdown's issues are probably more specifically all of the edge-cases that differ from implementation to implementation. Lack of a rigid specification and near-abandonment by its author didn't help.
I just found out about Lektor the other day. https://www.getlektor.com/ It's like Jekyll meets WordPress, written in Python by Armin Ronacher. He's the guy who wrote the extremely popular Python microframework, Flask.
It's a static site generator with a slick React powered admin interface intended for editors (non-programmers) to use. It runs locally like any good static site generator should and runs on Windows, OSX and Linux. With the click of a save button, it'll upload your statically generated site to any ftp or rsync server you choose ;)
Took me only 2 hours to have it building a page with a nav menu, localization, and a slick admin interface even though I had never even used Python before!!
All you do is declare your models, place references to them in your templates, and it handles the rest for you automatically.
The project is still a little rough around the edges as it was only released in December, but I'm already falling in love with it and I'm really excited to see how it changes the web once it gets built out a bit more.
Non-programmer editable static sites is a huge deal!!!!
Armin has historically been one of the most vocal of those critical of Python 3, and has even compared it to XHTML. He was pressured into porting Jinja2 and it cooled him on Python, if you read older posts of his. The answer should be pretty clear when you notice that Lektor fails on a print() not having parentheses (and not, say, a dependency).
Unicode in Python 3 is his problem, and there was one post I can't find on mobile where he started ranting about POSIX and Unix for some unclear reason. I can't follow him on a lot of it, as much as I respect his work, because if you read objectively it's pretty clear the reasoning is often there to support a predisposition. Meanwhile, my whole stack is Python 3 and I'm having a grand old time less the pieces where I had to sub in shittier libraries, and not a single problem Armin has ever raised about Python 3 has hit us. Not one. Most of it boils down to Unicode issues that have been issues outside of Python for 20 years.
This isn't to say Python 3 is perfect. (Far from it.)
He also often writes what I like to call the "Alex Gaynor Conclusion," which is tediously enumerating in the conclusion why you're going to call him wrong in his opinions which somewhat minimizes effectively disagreeing with him. There is a subculture of people who do this, and it mildly bugs me. Nothing against him; just an observation.
Anyway, port it and drop a patch, and I'll buy you scotch. I know better than to make any request other than that, and it's cooled me on using Armin's software in general (to my disappointment; Armin's Web stack has been a trusted friend through four different employers, from Werkzeug on up, and it's a massive bummer to see Lektor confirm suspicion).
Is there a list of new features in Jekyll 3 vs. 2? I looked at Jekyll's docs and can't seem to find anything. It has a nice guide of how to move from 2 to 3, but is there any succinct list of what new stuff you can do in 3, if anything?
The incremental building of the site is big, because it was beginning to become a concern just how well you could manage a large site with many posts and contributors.
On top of that, Liquid is finally being updated to 3.0, which comes with a couple of neat features.
It’s also nice to finally see an end to the Markdown discussion.
Thanks for asking. Right now we have no plans to merge it into GitLab CE. Can I ask what your use case is? How many people are using your GitLab installation and how many static sites are you planning?
No one was asking for it to be free. Currently it's tracked as a feature for enterprise users. They have 3 paid plans for non-enterprise users, and I'm certain many of those non-enterprise folks would love it.
Today, I tried out your service with a previously-unused domain and a brand new gh-pages repo.
When I ran into a small issue, I used the instant chat applet inside the Kloudsec control panel, and Steven quickly discovered the problem (I simply needed to remove the two A records pointing to GitHub pages, leaving only the Kloudsec A record).
Everything is working flawlessly so far, in regards to having TLS/SSL for custom domain hosted on GitHub pages. I especially like the option to enable HSTS for the domain's SSL. I wish GitHub Pages' own SSL on username.github.com offered that option.
All in all, painless plus quick, and without the unclean feeling that comes with Cloudflare's free SSL option. Additionally, I'm impressed with Steven's quick and quality assistance via chat and email.
edit: I've now noticed that there are large blocks of Javascript injected into my one-page test website. Ostensibly for the Speed Booster CDN plugin; I'll update after confirming the JS is gone upon disabling all plugins aside from the One-Click Encryption plugin.
edit2: Confirmed. Speed Booster plugin was source of JS injection. I suppose that's the drawback to a CDN who doesn't also host your DNS. Ironically, due to test site being small and static, disabling the Speed Booster plugin to remove all the JavaScript increased page load speeds.
Still, this doesn't detract from Kloudsec's simple deployment of LetsEncrypt SSL certificates for custom domains hosted on GitHub pages.
I don't know much about GitHub Pages, but if it's only for static pages, then why do you need SSL? I mean if you're not going to be sending sensitive dynamic data. Is it so people can't snoop the contents of your pages over request/response on a network?
I only have static, unimportant data on my site, but I use HTTPS in case someone's ISP is injecting ads or scripts into their pages. I don't want people to think that's part of my website.
I'm working on a static hosting service. We are working on SSL and making that easy. Would you be interested in trying the beta? http://www.statichosting.co
The cost is a non-starter. The main reason I go through the hassle of writing compilers for my websites is that I want them to be long-lived.
Presently, I use Nearly Free Speech as my hosting provider. Their pricing scheme for static sites costs me about $2.50/yr and I can maintain an account balance. My $50 account balance will keep my site online for two decades whereas it would buy me only ten months on your service. (Not to mention that Github hosts static sites for free!)
To consider another service, it wouldn't just have to beat the cost but instill a sense of confidence that I could trust the service with my data for the foreseeable future. A few features could tip the scales though:
- Open ID auth instead of basic access auth
- Easy SSL setup (gethttpsforfree.com was recently a huge help)
- Inexpensive hosting for a very low-volume mailing list with HTML archives
Nice. One way you could distinguish your service from all other options (S3, Github Pages), is to support the history API for single page webapps. I'm hosting a static site on EC2 instead of S3 because I need URLs to fallback to index.html. Literally for this one nginx rule:
location / {
try_files $uri /index.html =404;
}
Also, I'd like to try the beta of your service, just signed up. My email is in my profile. Thanks!
I know. We haven't added SSL to our site. That's one reason we are still in beta.
My partner and I are finishing up a CLI app and then SSL comes after that. We are hoping to integrate nicely with something like letsencrypt.org, but we don't have a working solution yet.
I know from experience that HTTPS setup isn't as easy, nice, or cheap as it should be and we plan to fix that if possible for static sites.
Well, technically, it does. The unfortunate thing is that it also supports non-encrypted HTTP. In my opinion, gh-pages is one of those places where it's not a big deal; there isn't anything too private being uploaded, and all the pages that can be served are available publicly on Github.
Edit: oh, I didn't know that it's not supported for custom domains. That is a bit disappointing.
Great news. Congratulations. If anyone is interested in learning more about Jekyll I've put together a link collection called Awesome Jekyll @ Planet Jekyll [1] - it also includes a section on the history (evolution) of GitHub Pages. Cheers.
[1] https://github.com/planetjekyll/awesome-jekyll
It's a tradition. That's how awesome lists work. See the mother of all awesome lists -> https://github.com/sindresorhus/awesome for more examples. The idea is to keep it as simple as possible e.g. just a single README page. That's all.
Yeah I’m aware of that, but why? You can use GitHub pages with one markdown file; it would be the same contribution workflow but with a nicer end-user interface IMO.
Good point. Thanks. The first version was actually a links.yml Datafile with rendered with GitHub pages. The Dr Jekyll's Themes Directory [1] or the The Jekyll Showcase [2] still use this contribution workflow. Cheers.
Ah, I am referring to the use case where the site is rendered clientside via Jekyll, then uploaded to the x.github.io repo. (which lets you use plugins, among other things, which is why I thought that was the more frequent use case). Not the loading-markdown-directly workflow.
Jekyll 3 is pretty great. If you need any help getting your site hosted, I'm working on a hosting setup that is way easier than S3 or any other option out there.
We are in private beta and are looking for people to try it out and give us feedback. We think it's great and are looking for early adopters who want an awesome static hosting experience.
Pretty cool! If you can set up some sort of integration with Travis (which itself integrates nicely with GitHub), and you set up SSL, HTTP/2, good caching policies etc., you're golden.
Our focus is on simplicity and there are only two of us, so adding features in a way that fit our limited resources and vision is a bit tough.
We are working on SSL and making sure we have good caching policies by default. Travis and GitHub integration are things we haven't looked at yet, but will.
If you are looking for something right away before we have all those features, you might check out netlify. They already support a lot of those features and might be a better fit in the short term.
For more (alternative) Jekyll themes see the Dr. Jekyll's Themes directory [1] it also includes a command line package manager and setup wizard. Cheers.
PS: The site is build - of course - with Jekyll and GitHub Pages ;-) and open source [2]. Did you know that you can even use git submodules with GitHub Pages? Works great.
Hmm, I hate to be a downer but this is a bit of a disappointing announcement for a major upgrade - basically, one very minor addition and a bunch of features removed - not that they were needed/widely used, but there's nothing else to show for it. Am I missing something?
Also it's a bit unfortunate there's still no easy way to do site translation in Jekyll.
A lot of the Jekyll 3 changes [1] thus far are focused on making the development life easier: faster (incremental) local builds and a lighter, easier to install stack with fewer dependencies (no more native library dependencies out of the box, no more dependencies on Python and Node by default).
Correct, nothing really mind blowing if you have all of it already set up and a relatively small Jekyll site, but big news for new users (especially on Windows where the native libraries and multi-language support have been bigger hurdles) and for people with large sites both in locally developing and debugging them and also in Github deployment times.
My Jekyll work flow tends to involve: Write a blog. Publish. Recognise horrid markdown bugs. Go and fix already published blog.
I appreciate there are better workflows, but as a Windows user I'm not going to install Jekyll to publish locally and test, nor is my blog big enough to justify a test environment.
The "drafts" feature basically just takes a draft and publishes it. What would really make life easier is it the drafts feature would "publish this blog, but don't update the front page to link it". I could look at it knowing the URL, and get it right first.
That's my main use case. I've got my personal blog [1] setup as a Static Website Manager repository and connected to my personal AWS S3 bucket.
Whenever I need to make a little change I can edit locally in my editor of choice, commit and push to SWM where I can preview the changes before merging to my production bucket (all without installing Jekyll locally).
If I don't have my machine, I can also just login, edit the text and then follow the same preview/merge to deploy workflow.
As a fellow Windows user (at least at home) with a Jekyll blog deployed on GitHub pages, I would recommend using a web IDE such as c9.io or koding.com.
They are little VPSs with sudo access (and a private web server) so you can test "locally" there and then git push once you're ironed out bugs. In your Windows machine you only need a web browser.
Something that's possible with some static engines but not really catered to is the ability to include the contents of other markdown files into a page-
----page----
# Title
<< contents of /markdown/file >>
<< second file >>
<< third file >>
Useful if you have lots of sections that you want to combine in different ways, and update them all at the same time...
Frankly, Github did a very poor job at communication this breaking change.
I only recently discovered that most of my post got broken.
Apparently it's no longer legit to use "#Title", you need to "# Title" (and god knows what else).
Linking is broken too - in Jekyll 2 there was no difference if a URL ended in "/" or not - you were just taken to the page, now this is a massive, although fixable pain (see https://github.com/jekyll/jekyll/issues/4440)
As a result my site experienced 500% drop in organic search referrals from Google.
I got no single email from then announcing this change. Very unhappy with how github handled it.
With this change, Github has made Rouge the only (and mandatory?) highlighter supported. This is a problem for sites that disable Jekyll highlighting in favor of using something like highlight.js. It appears right now that there is no way to disable Rouge which is causing conflicts with my sites that use javascript highlighting.
Fun fact: GH Pages changed the way trailing slashes work, so all links to my site dotted around the Internet broke as soon as I made a change. I had to update all the permalinks in my post to explicitly include the trailing slash.
I was a little surprised to see that GitHub is essentially playing favorites with Markdown rendering engines. Is there a discussion somewhere that outlines some of the reasoning behind this pick?
For everyone who's thinking "It would be great if Github Pages supported X", I am building https://zammu.in/?invitation_code=HACKERNEWS . It currently supports Middleman, Hugo, Hexo, Octopress and Jekyll. I am planning to add more to the list.
For every Git push to the master branch it builds and deploys the generated site to Github Pages.
FYI: I've put together a static site showcase called Stay Static [1] that builds the same site (w/ pages, posts and links) for easy comparision with Jekyll, Middleman, Hugo [2], etc.
Hugo is great. The Go template language is somewhat unconventional and does not yet support nested layouts (as do Jekyll, Middleman, etc.), for example. Cheers.
Slightly off topic but is RoR still the web framework of choice for developers? Could be just me but it seems most unicorns still continue to use it, even with all of the Python/Node/PHP frameworks out there.
If I were to guess I'd say no, with the majority being Node.js, then a mixture of Rails, Python, Go, and Erlang for the rest. As a note, Jekyll isn't using Rails, it's just using Ruby.
In the beginning was RUNOFF from MIT, which originally had about the power of Markdown. More features were added, and it became nroff, then troff, the ditrofff, and macro systems were added on top of it. It became too hard to use for casual work.
Then there was TeX, which was a saner approach to what troff did. Macro systems were added on top of it. It became too hard to use for casual work.
Then there was HTML, which started out with about the power of Markdown. More features were added. It became too hard to use for casual work.
Then there was BBcode, which started out with about the power of original HTML. It didn't gain many features, and is still widely used.
Then there was Markdown, which started out with about the power of original HTML. More features were added. Macros have been added by at least five people, but haven't quite gone mainstream yet. When Markdown gets macros, it, too, will be too hard to use for casual work.
Next!