LearnCF / cfSnippets

Simple, practical cheatsheets for CFML
4 stars 1 forks source link

Switch to Markdown with YAML Front Matter #2

Open michaelborn opened 4 years ago

michaelborn commented 4 years ago

There are a few big downsides of using JSON:

  1. It's pretty hard to read the snippets as currently stored in this repo.
  2. It's terribly hard to add new snippets.

Consider switching to markdown format, with YAML Front Matter to store structured data (e.g. title and description) along with each code snippet:

  1. Super easy to read and create new snippets
  2. Safer from XSS attacks... I think?

PS. As a simple example, the Lucee documentation uses this exact format:

https://github.com/lucee/lucee-docs/edit/master/docs/04.guides/02.installing-lucee/02.windows/chapter.md

michaelborn commented 4 years ago

Obviously, this would need to be paired with a significant update to the site to support markdown instead of JSON:

  1. Update cbmarkdown to support YAML Front Matter via the YAML Front Matter flexmark-java extension.
  2. Convert all JSON snippets to markdown/frontmatter format
  3. "flatten" the schema since I don't think frontmatter supports nested objects
  4. Update the CFSnippets site to convert the markdown/frontmatter snippets to JSON / a struct prior to serializing in ES.
  5. The rest of the site should function "as-is" with no extra conversion.