Skip to content
Boards›Boards Feedback

Writing for the web & the Community Beta

RiotMontag··9 votes·5,402 views

I want to talk to you guys about writing, specifically about Markdown. If you're familiar with Markdown, BBCode, Textile, WikiCode, or other methods of writing for the web, I want you to be a part of this discussion.

Our goal with the community beta is to make the best use of your time as a contributor and as a reader of content about League of Legends. Writing is core to that goal. We need to have a great platform for writing to have fruitful discussions that are worth reading. Only join in if you're OK with a wall of text: I write a lot, but I try to make every word count.

What is Markdown?

Markdown is a minimal syntax designed to make writing for the web easy-to-read and easy-to-write. If you write in block paragraphs and use stars for emphasis, you're already writing in Markdown. The result is that most people can read and write Markdown without a lot of upfront learning. I'll go into some syntax examples, but if you're interested in details, check out the official Markdown spec at Daring Fireball. That's also a slight tease of the syntax style, since we don't support in-line links at the moment. We might in the future, in which case this sentence won't make sense.

By the way, all this exposed Markdown is 100% on purpose. I just think it's beautiful.

Where I'm coming from

I'll put my cards on the table: I'm a huge Markdown fanboy.1 Virtually everything I write starts in Markdown, regardless of where it ends up: an email, a guide, an announcement, a presentation, whatever. Lots of other smart people have written about why they like Markdown, so I'll steal the list from Brett Terpstra's two-minute Markdown explanation. Brett captures my feelings exactly:

It’s easy: the syntax is so simple you can barely call it “syntax.” If you can use an emoticon, you can write Markdown.

It’s fast: the simple formatting saves a significant amount of time over hand-crafted HTML tags, and is often faster than using a word processor or WYSIWYG editor. It speeds up the workflows of writers of all ilk, from bloggers to novelists.   It’s clean: Markdown translates quickly to perfectly-formed HTML. No missing closing tags, no improperly nested tags, no blocks left without containers. You also get 100% less cruft than exporting HTML from Microsoft Word. There’s no styling inline, nothing that will otherwise break a site’s design or mess with the XSLT formatting for PDF output. In short, it’s foolproof.   It’s portable: your documents are cross-platform by nature. You can edit them in any text-capable application on any operating system. Transporting files requires no zipping or archiving, and the filesize is as small as it can possibly get.   It’s flexible: output your documents to a wide array of formats. Convert to HTML for posting on the web, rich text for sending emails or importing into a layout program for final arrangement or any number of other proprietary formats.   It fits any workflow: You can make Markdown work with any workflow. It can speed up just about any writing-related process with very little setup. It can also be scripted all to hell, if you want, because plain text is the most flexible of any format known to computer-kind.

So that's me. I <3 Markdown. I could talk your ear off about email, document, and presentation workflows, but for now, I want to talk with you guys just about writing for discussions on the web, and specifically contributing to discussions on Community Beta.

Markdown and BBCode

Markdown started small and has expanded a lot beyond its roots as a way to write human-writeable and human-readable words bound for HTML, especially in the realm of web-based discussion. Some notable sites that use Markdown for discussion are:

  • GitHub
  • reddit
  • Diaspora
  • Stack Overflow
  • OpenStreetMap
  • SourceForge

BBCode has also had a big presence in online discussions, especially around games. Markdown and BBCode are siblings in the world of web-writing: they're both trying to making writing for the web easier. However, they have very different approaches to that task.

BBCode was introduced in 1998 as a way of adding simple markup to message-board-style discussion. Where Markdown tries to keep its syntax minimal to optimize readability, BBCode isn't shy about its markup. It mimics HTML/XML in its use of tags to denote formatting, and as a result, both BBCode and HTML suffer from a similar problem: you have to really learn BBCode to both read and write it. The result can be difficult to parse, even with knowledge of the syntax.

You guys have all already absorbed that knowledge and you probably don't even remember doing it, so BBCode reads and writes really easily to you. But I'd challenge you that it's worth considering Markdown as a replacement. Let's get super geeky for a second and dive deep into an example to look at how Markdown differs from BBCode. First, here's some HTML.

http://imgur.com/9TEPxRb

Certainly readable, but there's lots of extraneous stuff. Each paragraph needs 7 characters just to exist as a separate entity. Both blockquotes and lists need opening and closing tags to indicate them, and lists are anything but natural to type out. Links are the worst. To type a link, you have to type 15 characters, not includuing the URL. Writing the above in BBCode is a lot easier, but you can still see remnants of HTML's influence:

http://imgur.com/ZeJ1PQU

Still readable, and certainly more readable than the HTML, so that's a plus. Syntax character count is also down across the board, but it's still pretty high. Creating the link now takes 12 characters instead of 15. Character count for lists is also down, but it still takes 3 for a single list item as well as open and closing [list] tags.

This is the same text in Markdown:

http://imgur.com/oWuRmbW

First-level heading is a single character with an optional closing character. (I use the closing character because I think it looks nicer.) The leading space is also optional. Italics and bold are 2 or 4 characters respectively, 3-5 characters shorter than BBCode. Lists and links are elegant and simple. A list is just a series of items that start with a dash and end with a carriage return, and you can use a star if you like that better: only two characters if you count the space. Links are easy and still highly readable: two sets of opening and closing brackets for a total of 4 characters, down from BBCode's 12. Counting only syntax markup for each example, Markdown requires 68% fewer characters to produce the same formatting as BBCode.

68% fewer characters.

In my opinion, Markdown clearly comes out ahead in readability and elegance.

Tradeoffs

You do lose some things switching to Markdown, but I'd argue that it's a net gain in favor of clarity. Many of you who weren't already familiar with Markdown were probably perplexed that a single line-return doesn't create a new line2 or that you don't have as much control over things like indentation, text alignment, etc.3 That's part of what I want to dig in with you guys.

With Markdown, increased clarity comes with trade-offs. For example, if you have a lot of items with single-line returns, Markdown forces you to consider what you're really trying to convey with your text and apply the right formatting for the job. Let's look at some examples:

  • If it's a list, it would be a ton easier to read if you formatted it as a bulletted list.
  • If it's poetry or a medium that has specific line-breaks, Markdown still has you covered: you can add two spaces at the end of a line to force a hard return. Looks good to the reader and isn't a lot of extra effort for the writer.
  • If you've got a bunch of paragraphs only separated by a single line return, I bet we can all agree it's hard to read a wall of text with no line breaks. Consider two line returns to give your audience a breather. Plus, you get the benefit of proper web-styling: we now know that you're using paragraphs, and we can style them appropriately.

All of these are slight inconveniences compared to BBCode that nets a ton of clarity for both writers and readers, in my opinion.

Riot-flavored Markdown

But some trade-offs may not be worth it, or maybe there are features that you guys absolutely need in your writing that we haven't provided yet, and that's what I'd really like to dig into with you guys. We want to figure out what Riot's flavor of Markdown is, and we need your help to do it. I've already used a bunch of Markdown and MultiMarkdown formatting, like inline- and reference-style links and footnotes respectively, that we don't support today. Maybe we should. Or maybe we should add tables. Or wiki-like links to champion or item stats. We can do a lot, but we can only set our priorities and make good decisions decisions based on your feedback. Remember our goal: to make the best use of your time as a contributor and as a reader of content about League of Legends. With every decision, we're always shooting for that star on the horizon.

So talk to me about your use of Markdown, coming from a world filled with BBCode. What do you love about it? Where are your frustrations? Where are Markdown's trade-offs unreasonable? What would you like to see? What do you absolutely need? This is the place to talk about it, so go ahead, post away.

Edit: Cleaned up a few reference-style links now that in-line linking is available.

Footnotes

  1. I mean, look at these footnotes. That's not even Markdown proper. It's MultiMarkdown, which is a user-created superset of Markdown. I know, I'm a lost cause. ↩

  2. We've implemented a strict interpretation of the original spec on Daring Fireball. Not everybody does it this way. GitHub, as an example, respects all carriage-returns as a <br /> tag in output. I've had lots of discussions with Krylhos about this. They get heated sometimes. Yes, heated discussions about carriage-returns. I direct your attention to the above footnote. ↩

  3. We haven't implemented all of Markdown yet, so there are some gaps. As an example, full Markdown allows HTML inside properly-formatted Markdown, and it'll interpret it as is, so a lot of these issues are very solveable in the standard Markdown spec. Naturally, we have some security concerns about allowing arbitrary HTML, but allowing some HTML is not totally off the table or figuring out other ways to get around it. MultiMarkdown adds Markdown syntax for tables, as an example. ↩

39 Comments

Pryotra5 votes

As a man who knew Html before ever being exposed to bbcode, bbcode was as natural as breathing. It really is not hard to pickup, and is really clear in how it will look. I for italicize, B for BOLD, U for underline which this board needs, s for strikethrough, * for bullets, quote to guote people, ect.

The main problem with learning markdown on your site is that I need a dictionary to do it, in the way of your formating guide. Bbcode allowed the less tech savy people to skip the learning process, which I feel would go a long way here. If you want your user to use something, make it clear, yet simple.[I] and [/I] around text clearly italicizes things, and it is easy to go back and add formatting where neccessary. I don't even technically need shift, where as if my keyboard doesn't have a number pad, I still need to hold shift or use... sticky keys. shudder

However, I have been experimenting with formatting as much as I can in posts. I must say, markdown is better for formatting on the go, but it lacks clarity. What is the difference between this and this? The first one used stars, the second underscores. What about this and this? First one used underscores, second one used stars.

Also
who am I quoting?
Quotes feel bad without a way to refer to the OP
and I shouldn't have to copy pasta, then format to quote someone, that just feels bad.

Also, do I really need a character between Quotes? What if I wanted to respond to a quote with another quote!

feels bad man.

And while we are on Quirks, what is the difference between

  • this
    and
  • this

Protip: The first uses {*}, while the second uses -

While I'm still at this _ guess how I did this? It isn't what you think! _ * I can do it with stars too! * * Bold isn't necessary I think._ _*

So without further ado, let me end the annoying formatting and get down to brass tacks:

  1. Formating needs to be clear on its purpose.
  2. Redundant ways to do the same thing need to be eliminated, other wise they fight each other.
  3. You need to implement more basic features, like underlining, strikethrough, and links
  4. One thing I hate is the reliance on imigur. Our current boards don't need this, why does this forum? What happens if their service goes down?
  5. User friendly is key. If you go back to do your edits to formatting, bbcode feels friendlier. I shouldn't need a manual to figure out how to bold some text.

I really hope that was entertaining, and that the post preview isn't lying to me. Hopefully this educated you.

Sir Frosthaven1 votes

Impressive feedback as always.

RiotMontag2 votes

Thanks for your feedback. This is exactly what we're looking for: how someone used to BBCode approaches Markdown as a formatting tool.

  1. Formatting needs to be clear on its purpose.
  1. Redundant ways to do the same thing need to be eliminated, other wise they fight each other.

These two pieces of feedback are particularly interesting to me. I want to understand more why you don't like having the option to use different formatting styles in source. Some people might call that flexibility rather than lack of clarity, and I'd argue that each style of bold/italics or list items are pretty clear to a writer. I'll sometimes use - on first-level and * on second-level list items just for my own visual differentiation, as an example. For you personally, why do you feel redundancy is a hindrance?

\3. You need to implement more basic features, like underlining, strikethrough, and links

Agreed, especially on strike-through and links. I feel like underlining is potentially a non-issue with other methods available (headers, bold). How would you use each of these?

Also, this quote is also an example of how our current quote structure breaks a bit in a standard quote-and-response style, because it's auto-generating the numbers. I've escaped the numbers to compensate, but it's still showing the escape character \\. Might be something we can change later.

\4. One thing I hate is the reliance on imigur. Our current boards don't need this, why does this forum? What happens if their service goes down?

Why hate, out of curiosity? At the moment, it's much easier for us to scale if we rely on external services for media hosting, especially in a world where everything is easily accessible behind a link and players are already used to sharing them. However, a plan for what we would do if the service went down is not something we have at the moment, so I appreciate you bringing it up.

I also appreciate your feedback about quotes, formatting in quotes, and being able to easily indicate an author. It's certainly possible with Markdown, but it's more manual -- I would need to cite the author and link to the comment using linked text in a standard Markdown document. That's something we're thinking about.

Pryotra3 votes

These two pieces of feedback are particularly interesting to me. I want to understand more why you don't like having the option to use different formatting styles in source. Some people might call that flexibility rather than lack of clarity, and I'd argue that each style of bold/italics or list items are pretty clear to a writer. I'll sometimes use - on first-level and * on second-level list items just for my own visual differentiation, as an example. For you personally, why do you feel redundancy is a hindrance?

It's partially due to clarity. Why have 2 different tools that do the same job? I'll give you bulleted lists, as that makes some sense, but when underscores and stars can fight each other like I demonstrated, it gets confusing. even if I copy and past my last formatting example :

Like this: * Bold isn't necessary I think. *

You can see the format change. Copy pasta shouldn't come out different, yet it does because all the behind the scenes stuff I did doesn't carry over. If I am authoring a guide, I don't want there to be a chance someone mistakes my meaning because someone quoted me and the format changed. This might seem small, but realize this is a non issue in BBCode. BBcode, while bulky, is sturdy, and not easily broken through random button pressing. It either follows BBCode, or it doesn't. Markdown has these wishy washy rules that allow for oddities like this.

Agreed, especially on strike-through and links. I feel like underlining is potentially a non-issue with other methods available (headers, bold). How would you use each of these? (This quote is also an example of how our current quote structure breaks a bit, because it's auto-generating the numbers. I've escaped the numbers to compensate. Might be something we can add later.)

Well, there is an example in your quote of me. If you hadn't added the slash, I would have needed to find the OP to see which list number you were talking about.

Strike through would be used instead of delete personally, or in certain humerous places. While the latter isn't a big deal, the former can add a great deal of insight into discussion on what was once said, but now taken back. I hate it with the current forums that the delete, outside f spelling and formatting fixes, can change the entire point if people disagree with them. I know I can't force it instead of delete, but I feel that in guides or discussion it really has a place.

URL's look nasty. Plain and simple. with word wrap on replies how they are, the longer url's need to be given a scrollbar, which can look pants on head tarded on wider monitors, like mine. Another issue, but this is one way to ease it. Also, I like to use links mid sentence. It gives a clean look without interrupting your point.

For example, I could say click {link}here{/link} to go see the latest news.
Or I could say go to the following url for the latest news: https://news.google.com/

You can see which is cleaner.

As for underline, I personally use it in guides within points. For example:

  1. This is the point - This is an explanation of the point. {u}This is critical to the explanation.{/u} This is more explanation. {s}This is an older point I had in the expanation.{/s}This might be a revised thought to replace the strike through.
    This is personal opinion, not necessarily part of my recomendation, but it helps to clarify my thought process.

This would be an excellent way to add strike through and underline using underscores, just like bold and italicize use stars. This would kill 2 birds with 1 stone

RiotMontag1 votes

It's partially due to clarity. Why have 2 different tools that do the same job?

For me, flexibility. Markdown is optimized for readability. In practice, most people aren't going to combine formatting styles, so they're not going to be confused by _*funny bolding combinations*_ that often; they're much more likely to be consistent. So while it's possible to do something "wrong," most people won't, and you get the benefit of flexibility while preserving readability. In my opinion, this applies more to bullet styles than bold/italics. To me, using __underscores__ to indicate "italics" or "bold" is somewhat unnatural.1

The benefit of flexibility, in my mind, comes from surprise moments when you've internalized a system's logic and you can successfully extend it. It happens all the time on the Mac. You drag a file into the Terminal and it populates the entire path to that file, or you drag an image from the browser to Keynote and it properly imports it into your presentation (doesn't work on Windows). Those moments feel awesome, and it contributes to clarity. So for bullet styles, it's a cool moment where you think to yourself, "This looks like a bulleted list, but it's different from what I normally do. Let's see if it works." When you see it work, you're going to get the sense that the system understands you. It allows us to make things more flexible more often because writers will expect it and benefit from being able to access that power.

Footnotes

  1. Maybe we can make that mean "underline" as part of Riot-flavored Markdown. Dunno. ↩

RiotKrylhos1 votes

After doing a bit of research, we went with two tildes for strike through. Being able to link is also available.

As for underscores, I agree they should not be used as italics or bold. I think we can make use of __ for underscores, it makes the most sense and there are solid use cases for it.

Pryotra1 votes

Ok, I guess. Still wonder why _ can't become underline.

I'll have to try guide writing now that the icons exist.

Pryotra1 votes

I tried out links, but I seem to be following the guide wrong. (Here)[http://community.na.leagueoflegends.com/c/support/ru3IQfYz-problem-with-store?comment=0000] is an example.

I still haven't worked guides yet, but to me either the formatting guide isn't giving me proper format, or the format isn't being parsed.

RiotKrylhos2 votes

The guide is wrong, We'll get it fixed. Text should be wrapped in the braces [] and the link goes in parenthesis (). Sorry about that!

Pryotra2 votes

Hit the character cap. Ouch.

Why hate, out of curiosity? At the moment, it's much easier for us to scale if we rely on external services for media hosting, especially in a world where everything is easily accessible behind a link and players are already used to sharing them. However, a plan for what we would do if the service went down is not something we have at the moment, so I appreciate you bringing it up.

Because I have been in the position of the 3rd party screwing me too many times to count, and have made it a rule as a developer to stay self sufficient. For a recent example, Tampermonkey recently had an issue with an update (now fixed on both ends) that caused FEK to freeze your forums. Another example in another field is Tekkit now has 2 versions due to bukkit falling off the map. I can't count how many times I have seen a guide that uses, for example photobucket, and the image won't show due to bandwidth limits. I could go on, but I think you get the point. It may be easier, but that ease of use is costly, too costly for my tastes. That, and when it breaks we get those nasty urls again. I don't want to click to see a relevent picture, I want it to just be there. clicking to expand is different, at least I'm not face checking the link for what I hope is a picture of what I want to see, instead of gore/porn/goatse/virus.

I also appreciate your feedback about quotes, formatting in quotes, and being able to easily indicate an author. It's certainly possible with Markdown, but it's more manual -- I would need to cite the author and link to the comment using linked text in a standard Markdown document. That's something we're thinking about.

Might I suggest a WYSIWYG way to quote people? like on the current forum, you can click a button to quote someone. Sniping will be more difficult on longer posts, maybe, but quotes currently really need work currently. I wish you luck.

RiotMontag1 votes

It may be easier, but that ease of use is costly, too costly for my tastes

I see your point. I'm not sure I agree with your total aversion, but it's worth considering strategically. I'll make sure our devs see this, and we'll definitely talk about both your concerns and a mitigation strategy for external service failure in general.

I do see a huge boon to relying on external sources for certain things: they will always, always do a better job than we will at those things. If we try to be all things to all people, we'll be half good at everything and not great at any one thing. If we can leverage third parties, though, we let them do what they do best, and we can focus on what we do best. So it's a trade-off between power and stability, and we'll do our best to land on the right side of that trade-off.

Might I suggest a WYSIWYG way to quote people?

I think in all cases, we should have a toolbar and an editor that automagically inserts formatting while commenting. As an example, let's say we create a way to quote people and link back to the author. We might also build a toolbar so you can select some text; you hit a button; the editor sucks in both the author, the text, and the text formatting; and then it creates the proper formatting for you.

Similarly, lots of Markdown editors allow you to use CTRL+B or ⌘+B to insert Markdown formatting (same with I). All those quality of life changes are on our radar.

JustMatt3 votes

I love Markdown because it's like writing a post in a more convenient version of HTML; since I'm in control of everything I type, I know that it won't be affected by things like copy/pasting over font formatting, weird snippets of code, or whatever else. It's a lot more convenient to type asterisks around something I want italicized instead of typing <i> and </i>. Also, the way links work (set a definition, be able to use it anywhere in the body) is awesome and saves a lot of time.

I'm a full-time writer, and instead of writing things in Word or in a CMS, I use Markdown because I can save what I write in .txt, which is universally accepted by a lot of programs, and doesn't insert weird code like .rtfs or .docs do. If anything, a lot of apps for tablets/phones will allow you to edit .txts, which in a pinch is great.

Basically, if you use Reddit, you've used Markdown, and if you do a lot of writing on the web, it's one of the most convenient systems to use in order to work quickly.

I use http://softwaremaniacs.org/playground/showdown-highlight/ in order to do most of my editing. You can put Markdown in the left pane and have a preview show up in the right. However, the thing I like most is the HTML export that you can access from the right drop-down. Format a post, copy/paste the HTML and you've got something that can go directly into a blog. The only thing is that it doesn't save documents, but if you're writing something in one sitting, this is aces.

RiotMontag2 votes

I'll allow myself to geek about a little bit about Markdown workflows.

This is a really cool tool. Another native editor I'm a fan of is Mou for OS X that does something similar. Mou also renders its Markdown in-place, so you get some extra feedback when you're writing that something is formatted correctly. You can also edit the CSS it uses to render Markdown as HTML. This is pretty powerful, because it means you can totally control the output styling. I spent some time setting up a Riot.css file that uses all our brand colors and fonts, so I can write in Markdown and output something that looks pretty professional right away.

Another native app I'm a fan of is Byword for OS X. Best $10 I ever spent. It has a beautifully minimal full-screen mode that I prefer for longer writing sessions. (I wrote this post in Byword). It also renders Markdown in-place, but it does it very artfully. Syntax gets a light-gray treatment that makes it fade away. Very classy. Example:

http://imgur.com/EF989Sk

brunoais1 votes

I'm a full-time writer, and instead of writing things in Word or in a CMS, I use Markdown because I can save what I write in .txt, which is universally accepted by a lot of programs, and doesn't insert weird code like .rtfs or .docs do. If anything, a lot of apps for tablets/phones will allow you to edit .txts, which in a pinch is great.

Try tex ;)

ArchMagus Frost3 votes

Hi Montag! I just wanted to say that i pretty much have absolutely no experience with web writing. Im taking a couple of programming classes at college, but they dont deal with web writing or anything. So just from the stuff you've said i can honestly say that the simplest one for me to grasp is Markdown. It seems a lot simpler to format and such, but to me, the most important thing is that anybody with no experience with code whatsoever will be able to understand the concepts behind it. it could be as simple as skimming down your discussion here and getting a slight understanding of how to format their page. But the fact is that its relatively simple.

I have been playing league of legends since JarvanIV was released in S1 and ive never really been involved in the community outside of the game so i feel like its about time for me to contribute something to the new community. I love what you an your coworkers are doing for us and id like to help out however i can. I would imagine that being able to add tables and graphs to a thread would be pretty awesome and Im sure that a lot of people would find that rather convenient. Im not sure if this is a thing yet, but i know on the regular forums ive seen threads with polls that people can vote on for different things ie. http://forums.na.leagueoflegends.com/board/showthread.php?p=24847697 maybe im just crawling outfrom under my rock here, but is that available for anybody to do? or would that be another thing to consider? Anyways, thats my input! Thanks for all the stuff you're doing for us!

ploki1221 votes

oh yeah, multioption polls are a must have imo...

RiotMontag2 votes

Thanks for your feedback HyperFang. I'm happy to hear that Markdown does feel more natural to you, as someone who doesn't do a lot of commenting. Also appreciate your thoughts on polls. I've noticed on other platforms like Reddit, they generally link to polling software rather than host their own. As an example, you might click a link on Reddit and be taken to a Google Form, or the summary page for a Google Form survey. Thinking about how you'd use polls, would that be sufficient? Why/why not?

Tables and graphs are definitely on our radar. They can be tougher to add because of syntax and formatting, but there are already some Markdown-like versions of tables, such as MultiMarkdown's: https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide#tables

Edit: I should also clarify, when I mean writing for the web, I mean writing that's bound for a web-based publishing medium, not necessarily writing HTML.

ArchMagus Frost2 votes

Oh yeah, that would definitely be good. Im not entirely sure how it would be done, but just having access to a polling platform would be good as long it would be easy to use! I think that would allow for community opinions to be brought to light on some fun topics and just getting to know the community a bit better in general.

  • thanks for responding btw I have never had a response from a Rioter b4! :)
Pryotra1 votes

And if those polling services you would use happen to go down?

These are your forums, you should be able to function normally if someone else entirely goes down for any reason. It is for this reason I hate the imigur use on this board, though that is another discussion.

Rule of thumb is, if you have to rely on something else, you will fail without it. I can name quite a few instances I have seen and experienced where this became an issue.

ModCaptainMårvelous3 votes

Testing header system

( To me that comes up as pound sign, space, testing header system, space and pound sign. No special text here. Also, Imgur is broken on the forums for some reason. Not sure if everyone has this issue or it's just me.)

If I may provide the view of a writer in terms of content-based writing (As opposed to discussion-based writing), I'd love to share my thoughts on this:

Foremost, the fact that markdown uses less characters is EXTREMELY useful for writers. This beta used to have a severely limited character amount that writing a long story was impossible (This has since been updated from the measly 2k to a generous 16k character count). That being said, markdown using less characters for each designated format is very useful. I can definitely put more into writing than having to limit myself due to bold/italicized/etc.

I do have to say that it can be a bit difficult to grasp at a glance. As someone who has used BBC and forum-style formatting ( AKA [b][/b] for bold, [i][/i] for italics, etc), I do have some trouble adapting to the asterisk style that's here. For example:

Blah blah blah

That's Bold and italicized. Yet there's no sort of reference for that in the formatting guide. Sure it's "Well duh just add 3 on each side". But at the same time, ordering lists is EXTREMELY specific.

*list *List

See, to me that should be a list item. But it's not. I had to mess around before finally cut-copy-pasting into the text box to figure out that there needed to be a space, then an asterisk, then another space, THEN your list item. It'd also help to say that you have to make every single list it's own paragraph, or else you end up with something like this:

  • Look at me I am putting a list right under a paragraph.
  • Wait this isn't working oh no!

Part of that comes from not being able to put text DIRECTLY under a paragraph (Which I'd hope there is a fix for) but so far that's just a minor inconvenience to me.

Block quotes aren't so bad. Though I think it'd help to note that the block quote only ends after starting an entirely new paragraph without any > marks.

One thing I really want to stress again is changing the formatting guide to instead be a quick insert system where you can highlight large amounts of text and hit a button to insert bold text, italicized text, etc. It can be somewhat of a pain to go through and carefully set out where you want certain types of text but I forsee this being more of a problem with bulletin points and the like.

Overall this system does take some getting used to but isn't so bad. While I prefer the [b][/b] style of formatting because it's quicker for me, this isn't so hard to be used to. Though, as a closing note, I'd really like strike-through/underline/possibly highlight on the list of formats to be considered.

Thanks for reading this and sorry if I went over stuff you already covered but I missed and/or neglected to see.

RiotMontag2 votes

Testing header system

This should come up as #. We don't actually support headers as of today. I'm going back and forth with devs about whether we should, but I use it anyway because I think it works well enough for my purposes.

Also, Imgur is broken on the forums for some reason.

We're aware. That's a bug we're going to fix.

See, to me that should be a list item.

There's a little bit of fuzzy-ness to the original spec on Daring Fireball, and things like this come up often: should a space be required after a list item to indicate that it's a list item? The spec does't say. Different parsers treat that differently, but most require the space, likely because building in the flexible logic to distinguish between a list item and a statement that starts with a phrase in italics can get really, really tough.

I'm personally all for flexibility, and I agree that what you've written should probably be considered a list item. Of course, I don't have to build it, so I don't have to consider cost/benefit. Something to consider for the future. I appreciate the feedback.

I had to mess around before finally cut-copy-pasting into the text box to figure out that there needed to be a space, then an asterisk, then another space, THEN your list item

You can start with a *, no leading space required. If you want to indent, then you'd use leading spaces to make this output:

  • First-level item
    • Second-level list item
  • First-level item

One thing I really want to stress again is changing the formatting guide to instead be a quick insert system where you can highlight large amounts of text and hit a button to insert bold text, italicized text, etc.

I'm also a big fan of this idea. Lots of Markdown editors do this, and i think it's huge both as a learning tool and just for speedy writing.

Though, as a closing note, I'd really like strike-through/underline/possibly highlight on the list of formats to be considered.

You're not the only one. =c) Definitely something we're considering.

ModCaptainMårvelous4 votes

Thanks for the help! It's really awesome how much you guya are listening to feedback and working on this system. Damn near refreshing!

RiotMontag1 votes

P.S. Headers work now. =c)

RiotKrylhos2 votes

And imgur links

Zielmann2 votes

At the moment, my biggest problem with markdown, as implemented here, is the complete lack of clarity within the Formatting Guide itself for some of the items. Some are straightforward (bold/italics). But lists had me confounded to the point of anger when I first tried to use them. Having figured them out, I can say that it's not that bad. But all that frustration could have been curbed by setting up the formatting guide on the 'Basic' page the same as the 'Paragraph' page, where you indicate when {space} and {enter} are necessary.

I don't mind learning the new formatting at all. And I've already gotten pretty used to using the bit of markdown that you guys have on here. I can say that it definitely does flow better than having to type [i][/i] every time I want to italicize something, for example. And the various combinations of spaces and enters required to put lines of text where I want them are becoming second nature already. But you have to give us the resources to see exactly how to get the output we want the first few times we use it, so we can learn it. If not, we're left randomly hitting space and enter and hoping we hit the right combination to put things in the right place.

In terms of what features to add, there are a couple that come to mind.

  1. In-line links are practically a requirement for me. I like when a post comes out looking relatively clean and polished, especially if I've spent a fair amount of time putting it together. And nothing ruins that polish like having to see some long URL floating about with its random hash string of characters and such just interrupting the otherwise-clean landscape.

  2. Header text is something I would like to see. I may not use it much, but I'm sure the people writing stories and/or role-playing might appreciate having them available.

  3. I would love to see the wiki-style links as you mentioned. Not only would it make it feel more integrated to the site, but it's just a nice feature to have. I actually used to frequent a fan-made League chat application. The guy writing it eventually put in an entire database of champions and items that you could view from the client itself. Whenever you would type 'sivir' or 'zeal', the program detected that, and would automatically make it link to the champion or item info.

And now I have a slight annoyance with the enumerated lists (I assume it would exist with a bulleted list as well). When you have multiple paragraph-long items, everything kinda blobs together. One of two things would help: Either have a way to allow a space between list items (I tried, and each item turns into a number '1' in the list), or modify the text alignment so that the additional lines are further indented, so that the item number sits in a column by itself, rather than getting absorbed by the new lines of text.1

Though that may just be an indication that I should have just written those out as separate paragraphs anyhow...

Footnotes

  1. Actually, in the post, it is displayed how I want it to be. This seems to be a bug/inconsistency with the preview pane, then. See: http://puu.sh/4FdLP.png ↩

RiotMontag1 votes

Thanks so much for your feedback. Love how detailed it is. You're a man after my own heart: I'm also a fan of polish, so I appreciate your thoughts on in-line links. I'm also a fan.

Multi-line list items is definitely possible in our version of Markdown. I think it's hidden in the formatting guide. Here's what it should look like.

  1. Multi-line list item

    This is the second line in a multi-line list item.

  2. This is a second list item.

To indicate that the second line is part of the list item, put a space in front of it. I actually put four for good measure. Should look like this in source:

  1. **Multi-line list item**

{space}This is the second line in a multi-line list item.

  1. **This is a second list item.**

(No code view just yet, so this is a little rough. Sorry about that.)

Edit: Also, I just reviewed the Markdown spec, and it looks like multi-paragraph list items are actually supposed to be indented by four spaces or 1 tab. At the moment one space will work, but I'd use four just for good measure. Also tends to look a little nicer.

Kajika912 votes

I really like the markdown fomratting style, easy and powerfull.

Also the Riot's preview makes things even easier and the guide is clear and simple.
So for me it's 100% better than bbcode and HTML.

I can't wait to get more markdown's option in this beta (dat ^ to add some humourist lines inside a post for example).

RiotMontag2 votes

Those are actually footnotes, from Fletcher Penny's MultiMarkdown. A good example of how these tend to look on the web is this post from Marco Arment. About 3/4 of the way down, you'll see a little superscript 1. If you click it, it pulls you down to the #1 footnote. At the end of the footnote, there's a little arrow that brings you back to your original place in the text.

Edit: Better example of footnotes in action.

Edit: I should also note, we have no plans to support them as of today. I'm just a strange person who likes them as a posting technique.

ploki1222 votes

First of all, I do believe that markdown is lacking on this community. But that much is pretty much know and acknowledged by everyone, so we'll skip that part.

Next, I do believe that Markdown is a wonderful way of formatting text. It's concise, precise and clear (once used to it).

However, the problem I see with Markdown is the same that I see Riot fighting against in LoL : Barrier of entry. Basically, ask your father (or in case you're roughly 15 and under, your grandfather) to format his text using Markdown, and he will slap you in the face before facerolling the keyboard because there's no [B] and [I] buttons up top.

So, like most apps you listed, you would need to have a mouse-only WYSIWYG editor, in my opinion, possibly triggered by a button at the far left/right.

N.B. Please check your font for that emphasized I, it's even worse than a slash (I vs /).
N.B.2 Also, make sure that if you keep the exact same possibilities as last platform (vBuletin), you fix the small inconsistencies like [INDENT] messing up line breaks big time... Also, pass that one to vbulletin team when you'll have time if you can, I may forget about it once again...

RiotMontag2 votes

Thanks for the feedback. An editing toolbar and WYSIWYG editor for Markdown is definitely on our list. I'd love to get your thoughts on a semi-WYSIWYG editor for Markdown that I'm a big fan of, Byword: http://bywordapp.com/-/img/byword_mac_01.png

It renders a lot of Markdown in-line, which I think is pretty good feedback as you're writing it. What do you think?

Speedkat2 votes
  • 0 spaces before *
  • 1 space before *
  • 2 spaces before *
  • 3 spaces before * * 4 spaces before *

    • 5 spaces before *

    • 6 spaces before *

    • 7 spaces before *

    • 8 spaces before * * 9 spaces before *....is this double-space listing intentional?

    • 5 spaces before *

  • 0 spaces before *
  • 1 space before *
  • 2 spaces before *
  • 3 spaces before * * 4 spaces before *
    • 5 spaces before *
    • 6 spaces before *
    • 7 spaces before *
    • 8 spaces before *
  1. This list is ordered
  2. This has one space
  3. This has 2 spaces
  4. This uses 3 spaces
  5. Why is this acting this way
  6. Does the number I use even matter?
  7. I headed this item with "893"
  8. Headed by "45", is this intentional?

Lists don't make sense to me. I can't speak for anyone else, but I'd prefer that my formatting (# of spaces heading a list item) carried directly over to how it displayed rather than (it seems) the Markdown choosing that the first item is base-level and carrying on upward from there.

RiotMontag1 votes

Good catch. The second root-level list with 5 space before it looks like a potential bug to me.

Handling list depth is a place where the Markdown spec doesn't give a specific rule, so we have to interpret it ourselves based on the "easy-to-read, easy-to-write" guideline. In my view, both ordered- and unordered-list spacing should consistently map to level. So, if X number of spaces increases level for unordered lists, it should do the same for ordered lists. X spaces should always = 1 level increase in depth.

However, I don't think you should ever be able to skip levels, so you shouldn't be able to start with a depth 0 (root) list item, then you put 2X spaces on the next line, and make the next item skip depth 1 and go to depth 2. Easy-to-write is definitely important, but it shouldn't break the reading experience by making your outline non-sensical. Riot Markdown should help you out there.

In my opinion, based on the Markdown spec and some of the editors I've used, X should = 4, not 2. 4 spaces or 1 tab is a common indentation mechanic in Markdown, and I think we should stick to it wherever possible. Something we'll talk about. What do you think?

Regarding ordered list numbers: Markdown doesn't care what numbers you use. You can be a good writer and use 1, 2, 3. You can also be lazy and use 1, 1, 1 or 3, 1, 2, and it would still resolve to an "ordered list" in HTML, which would always display as 1, 2, 3. So your experience in markdown "ignoring" your ordered list numbers is intentional. I'm less convinced this is a good thing than, say, requiring lists to increase by one depth-level at at time. I don't think you'll run into a need to make ordered lists with arbitrary numbers very often. That tends to not be very orderly. More likely, you'll run into a situation where you need to start an ordered list at a number other than 1 and increase from there. (I ran into that already in another post.) Might be able to find a solution for that, but my gut says it's technically challenging to do with HTML.

Speedkat3 votes

The list start is an attribute of the ordered list in HTML. So, to get (escaping for correct enumeration)

/5. stuff

/6. more stuff

/7. even more stuff

HTML can do

<ol start="5"> <li>stuff</li> <li>more stuff</li> <li>even more stuff</li> </ol>

Or at least you used to be able to do that. I haven't done HTML coding in like 2 years.

Good to know the rest of it is behaving as it should though.

RiotMontag2 votes

Nice call. I prefer this method, since it's the most-likely scenario for needing an arbitrary number in a list, and it preserves the ability for us to style lists and make them look nice.

Delta Sniper1 votes

Wow, ur asking us if we want something before you force it on us?

Tortferngatr1 votes

My personal issue with the format seems to be unclear results for when I stack different Markdown tags for when I want to do things like bold+italics or just...normal asterisks. While it's easier to type, it sometimes doesn't feel readable or...writable...when I'm trying to mix those.

I honestly question whether having to put 2 spaces to get an "Enter" is particularly readable for the poster. It feels annoying on Reddit (and trust me, I use the League subreddit a LOT,) and it feels (still) somewhat annoying here (although being able to see the markdown as it's edited helps here partially).

I think that, having no typographical design experience, having the ability to parse a special hybrid option between BBCode and Markdown sounds like a possible way to at least give some way to allow BBCode's reliability and maintain Markdown's flexibility.

For example

insert text here

would read as

insert text here

The approach is already used for in-comment champion pictures on the League subreddit.

Of course, it could be the product of staying up too late at night and trying to solve things when I should be asleep...

brunoais1 votes

As a web dev and as an active participant of phpBB dev since 2010, by working with the update of the BBCode parser and the addition of a WYSIWYG parser. I can say that Markdown and BBCode are cousins where one is not better than the other.

Markdown has many issues that the makers try to hide. Some of them I've been having in the PBE forums.
I won't mention the good side of Markdown because that has already been made by Montag. So it does not mean that I don't think it has good sides, I just don't want to repeat them.
Back to the main subject, here's some an examples of markdown's problems. I want to write an asterisk before and after the phrase:

simple, right?

Not really... There's a solution, though:

*simple,right?*

For that I was forced to use the HTML entity. I don't think that many knows the HTML entities. They are made using:

&#[insertNumberHere];

In the asterisk case, the code is 42 (sorry, I can't show you an example due to Markdown's limitations). This is not written anywhere and I was forced to stop and think for a while how could I display that character. It wasn't straight forward to understand that but I got it after making some experiences. You may search for it in one of my PBE posts.

That was problem No1. There's more!

BBCode is super easy for someone that knows HTML (specially in the HTML3.2 and HTML4 era), markdown... not so much... But then, most people don't know HTML and I have the selfish idea that most people who are comfortable with HTML are people who learn Markdown with ease... And most people have no clue what HTML is so... I'll let that slip as I agree...

With Markdown, it's not easy to tell **bold apart from ** italic when it is not well

Markdown is very limited in how much different things it allows

You can make the newline, paragrath, bold, italic, underlined, strikethrough, links, "sorta" citations (no identification of the source :( ) and not much more.
Just like wiki-like syntax, there's a very clear limit to where Markdown can survive. It can only hold until it turns into something way worse than BBCode where one starts to crave BBCode to come back.

TvTropes forums have a good example of this, IMO. The formatting options are a complete mess after the very simple bold, *italic *and underline.
BBCode has none of these issues and that's what I've been used to. Besides, there's a big tendency of making the BBCode tags with a single-word-well-described-functionality. Something that Markdown is powerless.

Markdown is about "what" content. BBCode is about "what and how" content

With markdown, you you have the power of telling what you are making. You can place the emphasis, you may give more strength to something by using bold, you may make a bullet list or a numbered list but then...
What if I want the list using roman letters? What if I want to use a different font for a small except of text? Can I increase the side of my text? I don't mean a title or something like that. For titles, there's already the "#"

My cope with Markdown

My experience with Markdown started with github. I was constantly checking my text to see if it was displaying right. Their option of "\n = <br>" helped me keeping myself sane with the discussions there.

I also make most of what @Pryotra states as my own. Lots of what he wrote is exactly the same as with me. At least, when I started with Markdown.

Markdown on PBE and me

With the LoL PBE forums I was introduced to a worse markdown... a markdown I was unable to use just by looking at it. My only save was the formatting guide that appears on the bottom right. I was able to keep glimpsing at it from time to time. I still hate that you tempered with the @href attribute! When I try to open it in a new tab instead, it opens the same page instead of the formatting guide. That was a huge cognitive failure for me.

brunoais1 votes

I ran out of space in the previous message:

Tl;DR

Careful when saying that Markdown is better than BBCode. You have to carefully analyze the user experience and the freedom you want to allow the user to have.

If you analyze well, one is not better than the other.
Anyway, for the PBE forums, I feel that Markdown does a better job than BBCode due to the limited formatting riot seem to want to allow its users to have.

brunoais1 votes

As it is now, how do I make a list using styled numbered sublists?

Things like (I tried to make without it formatting automatically):

1
    1.1
        1.1.1
        1.1.2
        1.1.3
    1.2
    1.3
    1.4
2
3
    3.1

etc...? When I try, I get this:

  1. Something. 1.1 something 2. 1.1.1 something extra.

It does not sound right

More from Boards Feedback

It's Time -You- Listen Riot:
Boards Feedback534 comments
1,727
votes
I think that the meeting went something like this...
Boards Feedback113 comments
611
votes
If This Reddit Style Goes Live, I'm Done
Boards Feedback203 comments
346
votes
An Open Letter to the Riot. With Pictures!
Boards Feedback211 comments
240
votes
New Board: Whining
Boards Feedback113 comments
208
votes
Did Riot really just...???
Boards Feedback104 comments
183
votes

More by Montag

What push-to-talk key do you use for voice chat?
Gameplay333 comments
52
votes
What's the catchiest LoL parody song?
Community Creations31 comments
10
votes
Iterating on the Discussion List view
Boards Feedback13 comments
5
votes
What good vote-driven threaded interaction looks like
Boards Feedback29 comments
4
votes