Open jaswrks opened 9 years ago
raamdev
commented
9 years ago @jaswsinc I was going to update your YAML example at the top to use proper comments (starting with #), but I realized that I wasn't sure if the # has to start at the beginning of the line, or if it also works inline (e.g., excerpt: [short description/summary] # (default is empty)
jaswrks
commented
9 years ago I was going to update your YAML example at the top to use proper comments
Oh, good idea. Yep, it could use some cleanup.
I wasn't sure if the # has to start at the beginning of the line
It only works at the beginning of the line. I'm beginning to think that perhaps we should consider integrating a more official YAML parser at some point. I am opening an issue here: https://github.com/websharks/wp-kb-articles/issues/49
jaswrks
commented
9 years ago @raamdev WPKBA now supports the full YAML spec. See: https://github.com/websharks/wp-kb-articles/issues/49
I updated the YAML above, and in the wiki article.
raamdev
commented
9 years ago WPKBA now supports the full YAML spec.
Woohoo! Sweet! :+1: :+1:
KB Article Creation Checklist
draftand eitherquestionsortutorialsdraftlabel, adddraft-finalizedlabel)draft-finalizedlabel, addpending)pendinglabel, addpublishedlabel)Moving this from the WP KB Articles wiki to a repo that will serve as the KB for the KB plugin :-) https://github.com/websharks/wp-kb-articles/wiki/YAML-Front-Matter-for-GitHub-Integration/_edit
YAML Front Matter Explained (All Optional)
When WP KB Articles pulls an article from your repo into WordPress for the first time, it will use the YAML Front Matter you provide at the top of the article, encapsulated by separators
------on their own line as seen above. Default values (as detailed above) will be used for any details that you do not define explicitly in the YAML Front Matter.Once the article is in WordPress, default values are no longer applied during any future updates. Any YAML Front Matter that is in the file will always be mirrored back to WordPress, but any YAML Front Matter that is not yet defined will remain as-is on the WordPress side; i.e. fields that are not in the YAML Front Matter can be controlled exclusively through WordPress.
This allows you to use as much or as little YAML Front Matter as you like. It comes down to a decision on your part as to whether you want to maintain metadata associated with an article from within WordPress (e.g. not including much, if any, YAML Front Matter); or you can choose to provide YAML Front Matter when you publish an article, or later during an update, and it will be mirrored to your WordPress installation.
To Help Explain This Further
Q: How can I update the title of an article?
A: If you did not supply a
title:in the YAML Front Matter, you can simply log into WordPress and change the title there. If you did define a title in the YAML Front Matter, you should change the title in your YAML Front Matter and wait for an automatic update to occur periodically.Q: I added YAML Front Matter, but now I've decided that I want control over the title from within WordPress instead. How can I accomplish this?
A: Remove the
title:from your YAML Front Matter and then log into WordPress and you'll have full control over a custom title from that point forward. Fields in your YAML are mirrored back to WordPress periodically (if they exist). Remove the field from your YAML and you gain control over it from within WordPress.Q: If I change the categories/tags in the YAML Front Matter, does my new set of categories/tags replace the old set? Or do they get added and others are preserved?
A: What you put into the YAML Front Matter is mirrored back to WordPress. If you change categories/tags in the YAML, any old categories/tags are removed automatically and your new configuration will be applied then.
Q: If I assign an article to one or more categories/tags that do not yet exist, are those categories/tags created on-the-fly automatically?
A: Yes. Any categories and/or tags that you define in slug format will be created automatically if they currently do not exist. This makes it very easy to use YAML Front Matter to categorize and/or tag your articles in various ways.
Q: What about
pubdate:in YAML Front Matter? If I set that tonowand then it updates again later will that change the pubdate each time the article content changes?A: It's for this very reason that a relative
pubdate:in your YAML will be used only during the initial insertion of the article when it goes into WordPress for the first time. Therefore, a relativepubdateis one exception to the rules above.For instance, if you set
pubdate: noworpubdate: +3 days, those are relative times. They apply only during the initial insertion of the article. Relative dates are bypassed on all future article updates.However, you can still change the publish date via YAML Front Matter. You just need to use a non-relative date; e.g.
pubdate: 2015-01-30,pubdate: Jan 30th, 2015, etc. Anything compatible with PHP'sstrtotime()function.