search

dsmjs / site

Gatsby site that is a WIP to replace the previous Jekyll site
https://site.dsmjs.com/
MIT License
1 stars 8 forks source link

Document markdown data structure #462

Open micleners opened 5 years ago

micleners commented 5 years ago

Currently there are several directories of markdown files:

My understanding is the meetings frontmatter provide relationships for the other 4 data types.

We want to have the relationships well defined and described for new comers to understand. So, the task at hand is to come up and document a clear data schema for the relationship between markdown files.

One tool that might be useful to document the data structures is: https://mermaidjs.github.io/#/

travi commented 5 years ago

its worth being aware that the relationships between the markdown files are currently defined here: https://github.com/dsmjs/site/blob/c2b478fe4773eac2bbf37783f26d3aa9481399c0/gatsby-config.js#L5-L10

travi commented 5 years ago

ideally, i'd like to see this done in a way that an image can be generated and referenced from a README.md in the content directory.

mermaid is a great fit for this type of approach since the text file can be versioned and an npm package can be used as a cli to generate such an image. i'm not sure they support support an appropriate chart type for representing foreign-key relationships, though.

travi commented 5 years ago

it looks like there is an open issue for adding a ER Diagram chart type, but i don't imagine that will get added soon. maybe the class diagram could work for now?