-
Notifications
You must be signed in to change notification settings - Fork 132
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
Markdown in .yml files (sort of) broken. A way to link externally? #44
Comments
I agree that from the end user point of view it just doesn't make sense to have markdown content indented. 1 is better option though. |
On the other hand, it's YAML's native format for inserting large chunks of text, so, there must be a better solution to the problem. |
Yes, I figured that the first option might not be possible, since it's trading off violating one format's rules for another's; that's why I wondered whether it wouldn't be possible to link the file–putting something like the following, in the
… which would also allow you to have pretty much any name for the content file (as long as the corresponding bit exists in the YML file), and it might even be more semantic this way: since the YAML file (named correspondingly with its template) is just a collection of key/value pairs and links, and the content text and media files are separate, with names according to their own context. |
Since there's only one What you think? |
yes, that could work, though not every page type will contain a content block called "content", nor necessarily contain only one block. I'm considering that the key file for any page is the
Note: the above syntax is most probably wrong |
My initial thought was than you can have as many
you'll end up with context containing all the variables from |
Ah yes, I just understood what you meant before. Indeed, that might be the most straightforward for the user, if the parser just looks for anything with an Any of the development contributors care to weigh in on this? |
This is really interesting. I like the evolution of the idea that @kvakes is proposing. As YAML doesn't have an external file-loading mechanic, one would have to be added, which would break with convention somewhat. But, the idea of using the filename as the key makes a lot of sense. In principal it feels like quite an elegant solution. |
HI, Anthony. Including markdown files as variables doesn't have any relation to YAML, it's just another way to init a variable in template context, so we're not breaking any conventions. And users will be able to decide whether to define long passages of text via YAML or via external files. One problem that I can see is that in earlier version of Stacey we could have $collections of |
Oh, with the 'YAML doesn't have an external file-loading mechanic' comment, I was referring to the idea of allowing I don't actually think that this will cause any conflicts with the |
I see what @kvakes is getting at with the potential conflict with In any case it suggests to me two thoughts:
Something like
which would assume the following is also possible
etc… I'm basing that on a combination of what I'm reading in the 2.3.x and 3.x documentation |
On the way home I thought about this further, and would offer one more observation: The But what's unique about the usage of So maybe the idea of parsing page value directly from files, keying on the filename, should be restricted to these types? I still think a syntax for referring to a file by name would be great (see my previous comment), but that's another feature request I think. Anyway I'm really excited to think this feature might see the light… good luck |
Hmm. No interest in this issue from the active developers? Maybe we should change the title ;) |
I love the idea, but I haven't had a chance to look at it yet. |
Cool. Glad to know it |
I looked around for thoughts on this indentation issue, only to find this issue after I posted this diatribe (mainly because the title wasn't very obvious at first), (#61). In summarization it seems most of my issues are bugging others as well, but I'm not sold on the inclusion of a .md file into the .yml file as the sole solution. My concern here (and correct me if I misread), is that with this approach your Title, Date, etc. is all in your .yml file, and your Content is in your .md file. That's a wasted separation. I think there really should be a two pronged approach to this.
So you end up with something like this (excuse the rough syntax): File Inclusion:
OR Block Inclusion:
If the parser gathers a key that ends with '(md)', then it looks for a file path in the value, if a pipe is found instead then it processes the following block as .md without required indentation. For content context, I also find it especially helpful to have the Date, Title, etc. in the same file as the content. Forcing a separation, makes it harder to keep up with all your content. I understand in keeping with YAML convention, but this is one area where YAML fails miserably in its lack of non-indented block literal handling, so its worth considering a slight "modification" here, to help maintain more honest user input -> output. |
Totally agree with these concerns and it is something that has been causing me issues. I tend to think that fencing markdown content is the better approach, as it does keep all of your content together in a single file. Which makes management much easier. This is the syntax I have been playing with: title: The Page Title
subtitle: +++
A shorter _piece_ of markdown.
+++
content: +++
## A markdown title
And a paragraph containing **bold** text.
+++
Where the +++s can sit on their own lines, or contain more than three +s: title: The Page Title
subtitle:
++++++++++++++++++++++++++++++++++++
A shorter _piece_ of markdown.
++++++++++++++++++++++++++++++++++++
content:
++++++++++++++++++++++++++++++++++++
## A markdown title
And a paragraph containing **bold** text.
++++++++++++++++++++++++++++++++++++
|
Kolber, There is also the suffix way
|
hey i like both the last two suggestions. @mentat-fr how would you close the tag, or would this automatically happen when writing a new variable below this? This may be a silly suggestion (from a user perspective), but if you are able to use a suffix to control wether to use markdown or not, then could you also use for example a semicolon or other character? like
|
I agree with @StephenLovell that it's not very good to store variables in different files. Two best solutions, from my point of view, so far are:
Since Stacey uses a very small subset of Yaml (?), we could just restrain Stacey from using Yaml, e.g. rollback to old Stacey variant where if a variable starts with \n then it is treated as Markdown. If we want to stick with Yaml, I would not change the syntax, it's just wrong to change something that is maintained by others, we no longer will be able to say that it is Yaml, because 1) users will be confused, because our Yaml is different, 2) the "wrong" syntax can have other dependencies in Yaml, or just philosophy we do not understand. We could also bug Clark Evans about it. But if we want Yaml's complexity, I would stick with *.md files treated as variables. It is not perfect solution, I understand it. |
thus far my favorite is
I get the desire to follow yaml syntax, but I'd sacrifice that standard over UX any day. This bends the rules, omits the indentation requirement and the pipe character. However your key is still a key, and you can do the markdown parsing easily by scanning all keys with .md at the end. Inluding external files is a useful option, but should not be the default. |
Unfortunately we need to specify both the start and the end of markdown content for parsing, otherwise the solutions listed above would be great. The basic problem is that we need to pre-parse the text file and convert the markdown blocks into YAML compatible text blocks before passing them back to the YAML parser. Unless you guys had some alternate ideas on how we could implement the above? |
Forgive me for my ignorance, but I guess I was assuming that the colon indicated the beginning of a VALUE and a new line plus next VALUE or EOF indicated the ending of a VALUE. A KEY with a .md suffix marks that it should be handled as markdown. So content: is just a regular KEY & content.md: is a KEY that is flagged for markdown parsing. In a nutshell To me that seems to omit the need to overtly flag the start and finish with +++, yes the preprocessor has to do a bit more heavy lifting, but it seems to me to be possible to incorporate the above to indicate the start and stop of VALUEs. Or am I missing something? |
It is a little more tricky than that. Take the following example: title: Page title
subtitle.md:
What if a colon appears in an awkward position within the text block?
Like: this.
content.md:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus luctus urna sed urna ultricies
ac tempor dui sagittis. In condimentum facilisis porta. Sed nec diam eu diam mattis viverra.
Nulla fringilla, orci ac euismod semper, magna diam porttitor mauris, quis sollicitudin sapien
justo in libero. Vestibulum.
It is very tricky for us to know with absolute certainty where the textblock ends and a new key starts. |
Have you considerd using YAML front matter style syntax, using YAML's native document syntax? |
I have, and I quite like the approach, especially as it is quite common these days. The problem is that I often have use for several blocks of markdown content — which could be handled with multiple YAML sections — but you lose the ability to name the variables. Which means you end up with a form of automated variable naming like |
@o-l-e right, so if you need a closing / ending why not implement a specific tag like
@kolber: whatever the solution, please let the standart yml identation syntax always work. |
@mentat-fr and @kolber: From a users perspective, i love the ability to have as many markdown blocks as i want, and its variable named what i want. This is one of the things that is very appealing with Stacey. And with such a clear simple language. I guess whatever final decision should fall on (for example):
Personally as the "visual" type, i have looked at others like Jekyll or similar things, but either they are too tricky to install(run shell scripts etc), or its too chopped up in bits and pieces(files here and there for any little line of text). I know that from a programmers perspective reusing bits is what its all about, but the great thing about stacey is the simplicity and accessibility that it gives designers like myself, or other non-programming types. People i have suggested stacey to, absolutely love it. The dropbox like way of dropping stuff in folders, and the simple nature of markdown(that is growing as a standard very quickly) in plain .txt documents. I think some of the new twig features are really nice, and see that stacey can be pushed so much further from a developers standpoint. But to be honest, i did not even know what a .yml document was until i read about it in this discussion group(not to say that it some day could become a standard). I don't want to seem defensive or non progressive, but personally i just hope whatever solution, it is something "human", simple and fast. |
I've been playing around with having .md (and .txt) files loading as variables and I quite like the result. It's a very easy solution to implement and separates quite neatly the page's properties (title, description, etc which go in the .yml file) from its content (images and texts). It's not a wasted separation, it's a useful and logical one. Everyone who worked with it found it intuitive and easy to manage, and they definitely were on the visual type side of things. |
Has there been any kind of resolution on this issue? |
@kariemil yes you can now use Markdown like so:
|
So, I was getting pretty stoked about the 3.x features, Twig and everything, but the switch to YML files breaks my favorite part about the markdown workflow:
with the more complicated syntax (indenting all lines of markdown content by two spaces), standalone markdown editors (Mou, Byword, Marked, etc.) don't understand it correctly, and the native previewing in those apps doesn't work anymore.
Therefore my question, is if (and how) there is any chance that either:
.md
markdown files from the.yml
file, allowing the possibility to write content in a native markdown formatThoughts?
The text was updated successfully, but these errors were encountered: