search

wpsharks / wp-kb-articles

KB Articles for WordPress; adds a new Custom Post Type.
http://wpkbarticles.com/
2 stars 1 forks source link

Feature Request: Snippets for GitHub Integration #87

Open raamdev opened 9 years ago

raamdev commented 9 years ago

There are scenarios where it would be useful to reference a snippet in a KB Article. With GitHub Integration disabled, a site owner could just use another plugin like WP Snippets. However, with GitHub Integration enabled, all editing takes place on the GitHub side.

A powerful addition to the WP KB Articles GitHub Integration would be support for snippets, where a snippet would just be a Markdown file inside the associated GitHub Repo (maybe in /wpkba-snippets/, a special directory that does not get treated as a Category). Then each snippet could be created with a unique filename inside that directory (not associated with any GitHub Issue, so the filename could just be something like snippet-a-fine-line.md).

Then to use the snippet inside a KB Article Markdown file, we could parse the KB Article Markdown file searching for any line that starts with /wpkba-snippets/ and then pull in the contents of the specified snippet file (e.g., /wpkba-snippets/snippet-a-fine-line.md on a line by itself inside the KB Article Markdown file), making that snippet part of the final KB Article that shows up inside WordPress.

jaswrks commented 9 years ago

Great idea. I've been contemplating something like this myself, and I was tossing some ideas around in https://github.com/websharks/wp-kb-articles/issues/10 also. Snippets seem more useful then acronym definitions—so thanks!

jaswrks commented 9 years ago

@raamdev writes...

Then to use the snippet inside a KB Article Markdown file, we could parse the KB Article Markdown file searching for any line that starts with /wpkba-snippets/ and then pull in the contents of the specified snippet file (e.g., /wpkba-snippets/snippet-a-fine-line.md on a line by itself inside the KB Article Markdown file), making that snippet part of the final KB Article that shows up inside WordPress.

So sort of like oEmbed for snippets. I wonder if that syntax would be better or worse than introducing a shortcode. Thoughts?

I'm thinking about the ways that it might be used. I can see it being very useful as a way to reuse small repetitive article fragments. Any other use cases you can think of?

raamdev commented 9 years ago

Snippets seem more useful then acronym definitions

Perhaps more useful, but I still love the idea of a definitions file and auto-linking certain words--so I hope that idea doesn't get scrapped! :-)

raamdev commented 9 years ago

So sort of like oEmbed for snippets. I wonder if that syntax would be better or worse than introducing a shortcode. Thoughts?

Well, looking at it from the WordPress-side, a shortcode would make more sense. But I wasn't looking at it from the WordPress side because with GitHub Integration enabled, none of the editing happens on the WordPress side. So if we used a shortcode, you'd be entering a WordPress shortcode into a Markdown file on GitHub... not very intuitive.

That said, if we used an oEmbed format and also added a WordPress shortcode, then the functionality could double as a sort of Snippets plugin for a site owner, where they use the GitHub repo to maintain a set of snippets for their site, that they can use anywhere on the site (in regular Posts/Pages). That might be kind of cool actually. Maintaining Snippets in a GitHub repo would allow for easily tracking changes and collaborating.

jaswrks commented 9 years ago

@raamdev writes...

Perhaps more useful, but I still love the idea of a definitions file and auto-linking certain works--so I hope that idea doesn't get scrapped! :-)

Good point. I will probably give this issue priority over acronyms, but I'm not scrapping the other idea altogether.

It will be interesting to see where this issue ends up. I have been a little hesitant when it comes to acronyms, because it feels like that sort of functionality could be made possible as part of a more powerful feature like this.

For instance, if there was support for snippets, I could create definitions with those, and then maybe there is a way to either:

raamdev commented 9 years ago

That might be kind of cool actually. Maintaining Snippets in a GitHub repo would allow for easily tracking changes and collaborating.

Of course that is teetering on feature-creep... I think if this were me, I would just use oEmbed style snippets and make this WP KB Articles-only functionality (i.e., not available outside KB Articles). If a site owner wants a snippets plugin, they can use WP Snippets. That said, it would be pretty awesome to add GitHub Integration to WP Snippets!

raamdev commented 9 years ago

it feels like that sort of functionality could be made possible as part of a more powerful feature like this.

I disagree. I think the acronyms/definitions file should be separate from a snippets functionality. Why? Because snippets are likely to be longer, multi-line, multi-paragraph things, likely each snippet having its own Markdown file.

A definitions file would be just that: A single file, with one definition per line. (At least that's how I was imagining it.) A definition would simply be displayed as a tooltip when the cursor is hovering over an acronym.

raamdev commented 9 years ago

it would be pretty awesome to add GitHub Integration to WP Snippets!

Actually, scratch that. I just started writing a feature request GitHub Issue for this on the WP Snippets repo and I realized that it would be overkill. Snippets are generally small enough that editing Markdown files would be too much work--the simple WordPress interface makes a lot more sense for the WP Snippets plugin.

raamdev commented 9 years ago

it feels like that sort of functionality could be made possible as part of a more powerful feature like this.

Another reason I would separate this functionality: Definitions won't support Markdown syntax. They're being displayed as a tooltip. Giving them "snippet status" gives the impression that you can write a full-blown Markdown definition for something, when in reality you shouldn't be writing more than a sentence or two at most.

jaswrks commented 9 years ago

@raamdev writes...

A definitions file would be just that: A single file, with one definition per line. (At least that's how I was imagining it.) A definition would simply be displayed as a tooltip when the cursor is hovering over an acronym.

I agree, I was trying to do too much with acronyms. I think if we go with your ideas for snippets we can get back to the basics when it comes to acronyms. Good good.

jaswrks commented 9 years ago

I was just about to give this a go, but I put the brakes on it—for the moment.

Pulling snippets from a GitHub repo is not that much different from what we are already doing with articles. We simply synchronize files in a special directory of the repo (e.g., /snippets/*) as a different Post Type in WordPress. Not much different, because it's still WPKBA keeping the WordPress side up-to-date, by pulling content from GitHub.

One problem that I see, is that snippets are a dependency that must be satisfied for any article which might use them. Satisfying this dependency is not a big deal, but it does create some challenges in code, which pertain to the parsing of an article.

With snippets, we now have two different types of content being synchronized on the WP side, where one of these must exist (snippets) before the other (articles) can be considered ready to present. Without careful consideration, it would be possible for articles to exist that reference snippets which are either a) outdated at the moment, or b) do not yet exist on the WordPress side; i.e., the processor needs to get this straight internally, so that every article which contains a snippet, can have that dependency satisfied at all times.

There are also two different parsing modes that we currently support. One is a preprocessor that renders Markdown in advance, and the other is to leave the Markdown as-is, and let the theme take over; i.e., assuming a theme like s2Clean (or Jetpack MD) is running.

Not a major issue, but I would like to think this through before I jump into the code.

raamdev commented 9 years ago

Great points all around. I see how this feature is going to require some careful planning.

I'm not sure how much of a priority should be given to this feature, as we've done fine without it across three separate Knowledge Bases (s2Member, ZenCache, and now Comment Mail). I'd put this on the back-burner for now.