-
Notifications
You must be signed in to change notification settings - Fork 278
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add URL links, paragraphs, formatting within fields? (HTML? Markdown? Latex?) #47
Comments
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... |
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. |
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. |
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. |
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.
This may certainly become an issue, unfortunately. |
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. You can see this in use in my own resume in the Work Experience section: http://registry.jsonresume.org/linuxbozo |
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
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 :) |
+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? |
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. |
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. |
We should continue to separate data and representation. Right now, everything is machine-readable and parsable. You have line breaks ( If we add a free-form If any, we should support a restricted set of formats, e.g. 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 |
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. |
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. |
+1 howardroark |
Quickly looking into CommonMark at http://spec.commonmark.org/dingus, the following markdown examples do not render properly:
As a technical writer, I find Markdown quite limiting and would prefer HTML support in addition to Markdown. |
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. |
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. |
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. |
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. |
Plain text is already the default and it should stay like this. |
@stp-ip +1 It's a neat idea, but let's stick to the basics for v1 |
@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/ |
Add example to score sub-section
After consideration, all fields should remain plain text and thus rely on the theme/converter for alternative formats. |
Is it possible to embed href tags anywhere?
The text was updated successfully, but these errors were encountered: