WIP: Markdown helper for Kramdown

Closes #1401 "Follow-up from "WIP: GitLab 9.2 release post"

What

The code block below (def markdown s) in custom_helpers.rb, added by https://gitlab.com/gitlab-com/www-gitlab-com/commit/40f823985ede789930d7d4f7dfb723547059a7b4:

  def markdown(text)
    Tilt['markdown'].new { text }.render
  end

  def markdown s
    Kramdown::Document.new(s).to_html
  end

Enabled the ability to add markdown kramdown to Yaml data files, then pull them into Haml files with = markdown(foo.bar). With only the block def markdown(text), there wasn't a way to do this (ref https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/6084/diffs).

This helper is gonna be helpful for other pages; e.g., if we want we can enable to /comparison/*:

From @rspeicher (https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/5551/diffs#note_30331287):

What? There's a helper directly above this one called markdown.

(...)

You can just add another method with the same name. It's replacing the previous one, so now the old one's there for no reason.

I also don't understand what wasn't working with the old one -- I'll open an issue to address in another MR.

Let's figure out what we're gonna do about it ;)

cc/ @SeanPackham @axil

changed the description

added Tech writing team backend release tech-writing-busy labels

assigned to @marcia

If I remove the first helper and use only:

  def markdown s
    Kramdown::Document.new(s).to_html
  end

it looks like it renders normally, but I'd rather confirm with someone more experienced in ruby/helpers.

If I use just the old one:

  def markdown(text)
    Tilt['markdown'].new { text }.render
  end

Middleman doesn't build:

changed title from WIP: Resolve "Follow-up from "WIP: GitLab 9.2 release post"" to WIP: Markdown helper for Kramdown

changed the description

added 1 commit

• 537be36b - remove previous markdown helper

Compare with previous version

@rspeicher what do you think?

assigned to @SeanPackham

@marcia I removed the Kramdown-specific markdown helper (the second one) from my local copy, ran bundle exec middleman and visited http://localhost:4567/comparison/gitlab-issueboards-vs-trello.html#dropdown and it worked fine.

If we switch to the new helper, it's Kramdown-specific. If we ever changed renderers we'd have to remember to update that. However unlikely that is, it's better to stick to the Tilt version which just uses the currently configured engine.

I'd prefer to figure out why the old one wasn't working as it should for this specific case.

added 1 commit

• df692054 - make a separate helper for Kramdown, keep the markdown helper intact

Compare with previous version

If we switch to the new helper, it's Kramdown-specific. If we ever changed renderers we'd have to remember to update that. However unlikely that is, it's better to stick to the Tilt version which just uses the currently configured engine.

I'd prefer to figure out why the old one wasn't working as it should for this specific case.

@rspeicher agreed, so I propose a 2nd thing: we create a separate helper for Kramdown and keep the old markdown one. We'll be both happy :) and we can investigate further why the markdown helper doesn't work, but keep the current solution up while we do that:

  def markdown(text)
    Tilt['markdown'].new { text }.render
  end

  def kramdown s
    Kramdown::Document.new(s).to_html
  end

If we want to use it, we call from Haml with:

= kramdown(foo.bar)

If we want to "debug" the old one, we do:

= markdown(foo.bar)

https://gitlab.com/gitlab-com/www-gitlab-com/commit/df692054a906253af118a79279755758901bff77

Thoughts?

mentioned in merge request !6152 (merged)

This MR got conflicts due to https://gitlab.com/gitlab-com/www-gitlab-com/commit/798d7cc18e80fb29a7f481e1f26bfedbed74bbc4, but https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/6152 does the same as https://gitlab.com/gitlab-com/www-gitlab-com/commit/df692054a906253af118a79279755758901bff77.

I removed the Kramdown-specific markdown helper (the second one) from my local copy, ran bundle exec middleman and visited http://localhost:4567/comparison/gitlab-issueboards-vs-trello.html#dropdown and it worked fine.

I don't think that this page had any markdown content in it. And I don't think this was ever working for non-haml documents https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/6001#note_29432624.

If we switch to the new helper, it's Kramdown-specific. If we ever changed renderers we'd have to remember to update that. However unlikely that is, it's better to stick to the Tilt version which just uses the currently configured engine.

We rely so heavily in Kramdown that I doubt we'd change any time soon.

closed

https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/6152 includes this change, so closing.

Thank you both @axil and @rspeicher :)