Feature: support for formatting in summary field

[steve-perkins]

First of all, thanks so much for all of the effort that has gone into this!

One thing I'm not crazy about with the FRESH and JSON Resume formats is the top-level about or summary field. It's modeled as a single string with no formatting, but it would be great if some support for formatting were possible.

The buzzword-cloud that's generated from the skills section is terrific for younger developers without a lot of job history. However, my anecdotal experience is that for older professionals with a career under their belts... you're better off with a summary section that simply lists a few free-form bullet-point highlight sentences.

The skills model forces you into a "category -> buzzwords" structure, while the summary model forces you into a "paragraph with no line breaks or formatting" structure. Bummer.

My proposal would simply be to add support for HTML or Markdown formatting within the summary field (at least newlines and bullet-points, if nothing else). Of course, there would be some challenges here:

1. You'd have to parse newlines in the summary field (I'm not sure if JSON has any support for multi-line string fields, or if you'd have to just embed \n characters within a single line).
2. More importantly, templates would have to recognize and parse formatting as appropriate for the target format. The HTML template would have to replace \n's with <br/>'s, and bullet-points with <ul><li>...</li></ul>. The MS Word one would have to replace them with the correct Word XML constructs, etc.

If this is too large of a feature request, then my fallback proposal would be to simply add some search-and-replace helper functions for Handlebars in src/eng/generic-helpers.js. I imagine that only two would be needed:

1. replaceSubstring : function( txt, target, replacement ) - returns a copy of txt, with all occurrences of substring target replaced by substring replacement. A Handlebars template for generating HTML output could then use {{ replaceSubstring summary '\n' "<br/>" }}.
2. enclosePrefixedString : function( txt, prefix, open, close ) - returns a copy of txt. If txt is prefixed by prefix, then that prefix is stripped and the string is instead enclosed by open and close. For the more tricky task of recognizing Markdown formatting at the beginning of a string, and replacing it with HTML formatting that must enclose the string. A Handlebars template could then use {{ enclosePrefixedString summary "/^ \* /" "<ul><li>" "</li></ul>" }}.

This fallback is a bit ugly, but it does take the responsibility for my feature request and push onto template authors who want to deal with it. I'm more than happy to submit a pull request for this myself if there is interest.

However, I am wondering if you don't already have a solution for this in the works now? When I look at the screenshot on the FluentCV website, the text shown in the summary field explicitly mentions support for HTML and Markdown formatting! Assuming that is legit, then will that support include line-breaks and bullet-point lists?

[hacksalot]

@steve-perkins Thanks for the excellent feedback. This is in line with HackMyResume's "Markdown everywhere" requirement. We're not quite there yet (see below) but the goal is:

• Markdown/HTML support for all textual fields in either FRESH or JSON resume. Of course!
• Flow Markdown to HTML, PDF, MS Word, LaTeX, and any other in-demand formats.
• Choose between inline and block-level Markdown formatting, based on the needs of the theme or user.
• Optionally enable/disable Markdown/HTML support globally, yielding the plain text equivalent.

HMR currently (v1.2) supports this to a degree. For example, this inline Markdown in Jane's FRESH resume...

  "info": {
    /* ... */
    "brief": "**Full-stack software developer with 6+ years industry experience** specializing in scalable cloud architectures for this, that, and the other. A native of southern CA, Jane enjoys hiking, mystery novels, and the company of Rufus, her two-year-old beagle.",
    /* ... */
  },

Gets bolded as you would expect. You'll also see a couple Markdown links and other (inline) Markdown decorations in her resume that are respected across HTML, PDF, and MS Word formats.

Regarding helpers: your requested functionality will be exposed for theme authors / devs / candidates who want to tweak things and beyond that, the internal resume representation Markdownifies things by default so this is very much something that is being built out.

Where the current support breaks down:

• block-level Markdown (your list items and paragraph-handling/line-break support) is weak.
• currently requires a FRESH-format resume (this will change in v1.3!)
• Markdown-to-LaTeX support is missing
• Markdown-to-Word only supports emphasis (*yay*), bolding (**yay**), and links ([yay](/foo/bar)).
• Markdown-to-Word does not support embedded HTML even though it's legal Markdown.

[steve-perkins]

Thanks, @hacksalot. A few questions to make sure I follow correctly:

1. When you say that current support for block-level Markdown is "weak"... do you really mean "non-existent", or is there indeed some way of using block-level Markdown currently in a limited or hacky manner?
2. You mentioned some things that are targeted for the next release (v1.3). Is block-level formatting (at least for the summary field) one of the things targeted for that release, or is it a longer-term goal for an indeterminate version?
3. A question related to the above. You suggest that my requested Handlebars helpers will be built out. Is that something that's already targeted for v1.3, or not yet on the release roadmap? Is that an interim solution until "full support" for block-level formatting is fully implemented later, or is that meant to BE the solution?
4. Assuming that block-level formatting is on the release roadmap (fully or via Handelbars helpers), do you have any idea of timeline? I don't mean to pressure or nag. It's just that if this were a long-term horizon thing, then I might be inclined to dabble with a personal fork in the near-term. If on the other hand it's already coming in Q1, then I'd probably just put this aside for now and come back to it in a few months.

Thanks!

[hacksalot]

Excellent question @steve-perkins. I haven't been able to answer them until now.

1. Soon you'll have the ability to selectively override the formatting on a per-field basis -- inline Markdown, block-level, various flavors of encoding. We'll call this the "nuclear option".
2. This was unclear when you asked it, but has clarified. Block-level formatting will be supported in v2.0 and on a limited basis in v1.x. OTOH, v2.0 is days/weeks away, not weeks/months.
3. More or less immediately, in terms of helper support, but there's been some slippage. This is near the top of the TODO list as of now (feel free to submit!).
4. Well the whole idea of HackMyResume is that you'd always play around with your personal fork if this question ever occurs to you. Jedi lightsaber principle. If you want a more packaged release, FluentCV:CLI or FluentCV Desktop are better bets.

[hacksalot]

Please comment if you have any additional input. Thanks!