Add URL links, paragraphs, formatting within fields? (HTML? Markdown? Latex?)

[jpe42]

Is it possible to embed href tags anywhere?

[thomasdavis]

So we do have a problem with content having to be plain text. I think this will have to be a constraint of the project because it complicates a few things. Unless anyone has some brilliant idea I don't know if this is a possibility...

[vote539]

Maybe any strings that are intended to contain long descriptive texts (work summary, reference, etc) could be parsed through MarkDown. That gives the ability for URLs as well as boldface and italics.

[thomasdavis]

As much as I love markdown(I built this over a year ago ->http://markdownresume.com/), I think we might have to throw the idea on the back burner.

Even if it made sense for the specification to do this, the templates that theme developers generate will have to support it also.

[vote539]

I feel like Markdown is widespread enough nowadays that template developers would not need to exert too much more effort to support it; there are drop-in plugins for ruby, mustache, handlebars, and so on. I think even if it doesn't make it into the standard, some template developers may start supporting it anyway, leading to fragmentation. Just my two cents.

[ocram]

But what about LaTeX exports instead of HTML exports? Developers who offer this will also have to make use of the markdown.

And in general, you can say that, no matter if the developer wants to support it or not, as soon as markdown is in the specification, everybody has to support it, further complicating the process.

even if it doesn't make it into the standard, some template developers may start supporting it anyway, leading to fragmentation

This may certainly become an issue, unfortunately.

[LinuxBozo]

I made my theme (https://github.com/linuxbozo/jsonresume-theme-kendall) support that in certain fields. See: LinuxBozo/jsonresume-theme-kendall@947e967.

What it does is use mustache's built-in method for displaying unescaped HTML, using the triple bracket, {{{ var }}}, instead of the default escaped HTML parsing done with the normal double bracket, {{ var }}. You have to remember to properly quote escape any HTML in your json however.
IE:
"Team lead and developer for <a href=\"https://disability.gov\">disability.gov</a>, the US Department of Labor (DOL) portal for those with disabilities to find help within the federal government",

You can see this in use in my own resume in the Work Experience section: http://registry.jsonresume.org/linuxbozo

[DonDebonair]

I agree that we should put this idea on the back burner for after the first official release.

But to add some idea: why no have a metadata field that tells the parser what kind of markup to expect in string fields? Something like

"_markup-format": "markdown" // could also be "latex", "html", etc.

It will still depend on the tool you're going to use, what kinds of markup are supported, but at least we make it explicit that way. We could also put a recommendation for a markup language, to go with the spec. I would suggest CommonMark, which is the future of Markdown :)

[JaredCubilla]

+1 for @dandydev's solution. I think an extra metadata field with the language is the way to go.

I have a question about this though; will the Markdown be parsed by the theme logic, or beforehand/something else?

[DonDebonair]

By the theme logic. Remember, json-resume is a specification, nothing more, nothing less. Any tool that uses your resume can choose to parse stuff or not.

[JaredCubilla]

OK, I'm fine with theme logic. The only problem with that is that we'll have to upgrade the themes we have now. Other than that, +1 again.

[ocram]

We should continue to separate data and representation.

Right now, everything is machine-readable and parsable. You have line breaks (\r\n or \n) somewhere? A tool that generates HTML may replace them with <br /> or </p><p>. A tool that generates LaTeX may replace them with \\ or \newline. A tool that generates Markdown may keep them as they are are.

If we add a free-form _markupFormat field, a JSON resume becomes completely impractical. What values to expect? You can't support them all. Your tool wants to generate HTML but suddenly encounters strange formatting in the text and openoffice in the _markupFormat field. What to do?

If any, we should support a restricted set of formats, e.g. [ "HTML", "Markdown", "LaTeX" ]. But I doubt even that would be the optimal solution.

What's wrong with plain text which any tool can convert to any form it needs? Your HTML tool may auto-link URLs from the plain text by wrapping them in <a />. What other fancy stuff do you need in a CV? A <canvas />? Ancient <blink /> tags?

[DonDebonair]

Your arguments are valid. I still think it is also a valid requirement to add some kind of formatting to longform strings. Maybe we should just pick one standard for text fields and stick to that. In that case I would propose one of the Markdown dialects, preferably CommonMark.

[howardroark]

Any updates on this? I think @dandydev's last suggestion to just assume Markdown makes the most sense. Markdown is designed with common sense in mind and is completely readable by humans in plain text form. Dialects aside the original implementation caught on because no one ever needed a manual to grok it. You just look at an example and run.

I feel this project is lacking if I can't apply any basic formatting. The point of a resume is to convey information to other humans and basic formatting is a necessary part of that process.

[dy2288]

+1 howardroark

[osg]

Quickly looking into CommonMark at http://spec.commonmark.org/dingus, the following markdown examples do not render properly:

1. item one
1. item two
   a. sublist item one
   a. sublist item two

1. item one
2. item two
   a. sublist item one
   b. sublist item two

As a technical writer, I find Markdown quite limiting and would prefer HTML support in addition to Markdown.

[stp-ip]

I would say we should strive to first get the data only representation working and having a representation language possibility in the spec seems unreasonable for now. If this is added, it should definitely be some sort of meta, hidden tag. But I think that all the representation could be done with custom fields and data only in conjunction with a specific theme.

[stp-ip]

My proposition is probably to have the data without any representation, but make it possible later on to overwrite text only fields via the meta data section.

Would could write something like the following in the data section:

...
"work" : {
  "name": "gardner AG",
  "description": "Gardening for the millennials"
  }
...

And in the meta data section one could add:

...
metadata.substitute = [{
  "section": "work['gardner AG']",
  "substitutes": {
    "description.markdown" : "Markdown enabled description.",
    "description.html" : "HTML enabled description."
    },
  }],
...

This is only a rough idea on how this could be done in the metadata section and needs to be revisited, when v1 is finalized and the metadata section is available.

[aloisdg]

Nice idea! I would love see this because it could enable a lot of formatting. We could use a tag like the one in http request or an enum.

Each template will have to use a flag with support : "markdown", "html", "asciidoc", "plain text", etc.

[stp-ip]

Great thing about having a plain-text data source as truth is, that themes not supporting markdown etc. could just fallback to the plain-text source.

[aloisdg]

Plain text is already the default and it should stay like this.

[phumke]

@stp-ip +1

It's a neat idea, but let's stick to the basics for v1

[aloisdg]

@phumke Indeed. This issues has the tag post-v1. 😉

Also, this one wont break the compatibility. It will be for a v1.x ! We can hope for v1.1. \o/

[thomasdavis]

After consideration, all fields should remain plain text and thus rely on the theme/converter for alternative formats.