Top level API design

[puzrin]

Suggestion: no global singletons - that's a great way to fuckup everything.

var Remarkable = require('remarkable');
var remarkable = new Remarkable(/* options */);

// change instance options
remarkable.set(/* options */ /*, reset */); // reset = true -> disable everything else

• Do we need call without new? (i think not)
• Do we need to export Lexer, Parser & Renderer classes? User can modify local instances via properties of remarkable exemplar.

Options:

{
  blocksep: '\n',   // ?
  innersep: '\n',   // ?
  softbreak: '\n',  // ?
  langprefix: 'language-', // css prefix for fenced code blocks 
  xhtml: false,     // ? <hr /> instead or <hr>
  html: false       // disable html blocks/tags by default
}

[puzrin]

Options (from marked, remarked, stdm):

• stmd
  • ? blobksep, innersep
  • softbreak
• marked/remarked
  • ? gfm
  • ? tables
  • breaks (? stmd softbreak?)
  • ? pedantic
  • ? sanitize
  • ? smartLists (what's that?)
  • ? smartypants (what's that?)
• temporary
  • code lang prefix?
  • ? xhtml style (pending / in

    ---

    etc)

Options, marked by ? are candidates to remove. Some are not needed to tune, some can be disabled via lexer interface, if one really needed (remarked.lexerBlock.off('nptable')). I'm very conservative about adding lot of options to API. This thends to create garbage, that nobody needs, but have to be maintained, and restrict future internals change.

[puzrin]

Option:

• html (enable/disable) - that can be controlled via lexers , but seems to be very popular, and worth to expose as top level option.

[puzrin]

Geek parts. Needed only for deep control, like tokens post-processing, before rendering.

That's very preliminary, and i don't like it. Just to remember, that we should provide easy methods to parse inlines only and so on.

var Remarkable = require('remarkable');

var md = new Remarkable({.. options ..});

// tweaks (usually not needed)
md.lexerBlock.at('nptable', null);
md.lexerInline.before('link', myFN);

//
// Simple run (most cases)
//
console.log(md.process(string));

//
// Advanced run
//
var state = md.start(string);

// when we need inlines only, not wrapped with p
md.lexerInline.tokenize(state, 0, state.lineMax);
md.renderer.render(state);

console.log(state.result);

[puzrin]

@jonschlinkert , see updated options list in first message. Only one for smartypants is missed (until autoreplacer done). Everything else nuked as useless. Please, check it that's enougth or not.

It's still possible to disable separate markup (tables, ...) via api, but i'm not sure we have to expose it to options. At least, until many people ask it.

Also advice better name for language prefix if possible. Now it's not clear that it's for fences. But i can't invent something short and without camelcase.

[jonschlinkert]

better name for language prefix if possible. Now it's not clear that it's for fences. But i can't invent something short and without camelcase.

I think a lot of users will be familiar with langprefix, IMO it's fine.

The only feature that I would like to see on the list is gfm. It's expected by marked.js users since it's turned on by default - and it makes sense anyway since the vast majority of our users will be github users. great table support would be awesome, but that's just nice-to-have.

[puzrin]

The only feature that I would like to see on the list is gfm.

I expected, that tables support will be on by default. And if someone wish to disable tables, he will do something like markdown.block('tables', false). Or may be (not sure) tables: false in options.

Is something wrong with this approach? Are there situations, when tables have to be disabled? gfm name in api looks like legacy mode.

[jonschlinkert]

gfm name in api looks like legacy mode.

You are probably right, it will take some time for me to get as familiar with the spec as I need to be. Everything you're saying makes sense.

and sorry, I meant to reply to this. I don't like the new github notifications, I never notice them anymore.

[jonschlinkert]

...and is it just me, or is anyone else find it interesting that the spec is being partially championed by Jeff Atwood? I know he has been "talking about markdown" for a long time, but I can't help but think about stack overflow when he mentions markdown. SO has the absolute worst implementation of markdown that I've ever used. It's painful to write on that site. I really hope the spec doesn't reflect SO's idea of markdown.

[puzrin]

be specific, what exactly you don't like.

[howardroark]

At first I was gung-ho about it all as it seemed to have a lot of momentum behind it. The more I watch it the more I worry it is becoming a programmers tool. Perhaps not intentionally, but nevertheless going that way.

I think Markdown is an idea that anyone can adopt. Once people use it and grok the simplicity of its control they will start to want it more. So many creative opportunities could come from Markdown if it was a ubiquitous writing tool. For one the HTML of the web would start filling with real semantic content.

I think the only fix is for John Gruber to get something going on GitHub and really spell out how he sees Markdown in the future. I suspect he never wanted to clearly define it so that it could evolve more freely.

[jonschlinkert]

be specific, what exactly you don't like.

@puzrin I like everything you're doing in this project. I meant stackoverflow.

For example, they don't use gfm, they require code to be indented for code blocks. Does anyone still do that? gfm allows you to identify the language, get syntax highlighting, creates semantic, contextual relevance for the content so it is more likely to show up in searches etc. IMO gfm does it right.

[jonschlinkert]

The more I watch it the more I worry it is becoming a programmers tool.

@howardroark, I'm not sure what where you're coming from. this is a programmer's project to build a parser/compiler for markdown. I'm excited as hell about what @puzrin / @rlidwka / @Kirill89 and team are doing right now. We're going to make this project amazing!

What impresses me about how @puzrin is managing the development is:

• he is trying very hard to stay as close to the spec as possible, only veering when the spec is not clear. in those scenarios I personally don't want to get into debates about what the spec should or shouldn't do, I'd much rather allow progress to happen.
• the code is brilliant. IMO we have the best team possible working on this. better than stmd. I'm confident of that.

Regarding philosophical issues with the language, how it will be adopted by the community, what users want to actually do versus what we release, these are all things that will necessarily need to be learned as we go. It's never good for the momentum of a project to kill progress by over-analyzing questions that are too hard to answer at present - e.g. paralysis from analysis. This is especially the case when there are plenty of cut and dried things that can be done without debate.

Remember that code can change, options can be implemented, and the API makes remarkable extensible. At the end of the day, regardless of the features we implement, the community and users will decide how markdown should be used.

[howardroark]

I 100% agree. The only element of whitespace that should be relevant is new
lines. That should be one of the first rules of Markdown.
On Sep 18, 2014 5:03 PM, "Jon Schlinkert" notifications@github.com wrote:

be specific, what exactly you don't like.

@puzrin https://github.com/puzrin I like everything you're doing in
this project. I meant stackoverflow.

For example, they don't use gfm, they require code to be indented for code
blocks. Does anyone still do that? gfm allows you to identify the language,
get syntax highlighting, creates semantic, contextual relevance for the
content so it is more likely to show up in searches etc. IMO gfm does it
right.

—
Reply to this email directly or view it on GitHub
#4 (comment)
.

[howardroark]

@jonschlinkert I needed that! Sorry, I was mostly just rambling about the
CommonMark stuff. You are right though, if I want to talk about the
philosophy of Markdown I may as well just go and start a document somewhere
myself!

I'm super excited for this project. @Purzin is doing an awesome job, and
has the perfect amount of sass!

I'm so using this once it's ready. Consider this my last troll-by until
things are released.

I 100% agree. The only element of whitespace that should be relevant is new
lines. That should be one of the first rules of Markdown.
On Sep 18, 2014 5:03 PM, "Jon Schlinkert" notifications@github.com wrote:

be specific, what exactly you don't like.

@puzrin https://github.com/puzrin I like everything you're doing in
this project. I meant stackoverflow.

For example, they don't use gfm, they require code to be indented for code
blocks. Does anyone still do that? gfm allows you to identify the language,
get syntax highlighting, creates semantic, contextual relevance for the
content so it is more likely to show up in searches etc. IMO gfm does it
right.

—
Reply to this email directly or view it on GitHub
#4 (comment)
.

[jonschlinkert]

@howardroark, no worries, you care a lot about what's happening in this space and you're lending your voice to ensure things head in directions that's good for all. we'll need champions, so I'd love to see you stick around help make get the word out when the time is right!

[puzrin]

After thinking a bit,

• this should be moved from options to renderer properties:

  {
   blocksep: '\n',   // ?
   innersep: '\n',   // ?
   softbreak: '\n'  // ?
  }

• this should be added back in options, but set true by default:

  {
   breaks: true
  }

[puzrin]

Reference http://talk.commonmark.org/t/why-not-allow-images-without-alt/617

I tend to add option

{ easyalt: false }

to allow skip empty [alt] for images. If nobody like it - that will be my personal undeletable madness :) . It will be off by default, and will not harm anyone. Or, may be it can be published as separate package, that's also acceptable for me. Not decided yet.

[styfle]

I just found remarkable today and it looks very interesting. It seems to be targeted towards a commenting vs page/content creation which is what I am looking for.

Regarding the API, the html and xhtml flags are a bit confusing. Is html for input and xhtml for output?

[puzrin]

See https://github.com/jonschlinkert/remarkable#usage and demo.