Add method to import markdown for schema or property-level supplement
jautor opened this issue · 4 comments
The v3 support simplified the content supplements, but the new support is showing the limits of the approach. Large blocks of text, especially when code snippets and other formatting are involved, are difficult to encode into a JSON document. Furthermore, any future content that could incorporate diagrams or other image files won't be possible.
The supplemental text method is good for simple additions, but we should add another mechanism to point to an external supplement file. To keep this from becoming confusing for content creators, perhaps the content file should apply to only a single schema, and match content by heading. Suggest top-level headings for Introduction, Properties and Actions, with 2nd-level for property and action names.
A further thought is that this content could be auto-detected using filename conventions and a target folder to pick up markdown supplements like we do for JSON payload examples.
Hi @jautor, I've been working through this on a branch and I want to check in before I merge this one. I've defined a format with delimiters that look like markdown headings, except that I've added dashes (e.g., "#--" instead of "#") to make it clear that these are not headings. A simple (and unrealistic) example is here:
So this basically supports intro, json payload, and property details (the last, by property name). It doesn't support Action names, because we phased out Action Details as a thing you could add with config awhile back, and I'm hoping we don't need to bring it back. :-) In fact, if you confirm we don't need that, I'll remove a few routines in the code that aren't called anymore!
As we discussed, there would be one markdown file per schema, and the directory for those files is specified in the base configuration file (as "supplement_md_dir"). Documentation at:
@akf The new structure looks fine and so does the config file entry.
I'm afraid we will want the ability to add supplemental description text for individual Actions, so that will need to stay. I don't remember what we said about action details in the past, but as Actions are the most complicated part of the interface, I can absolutely see us placing more descriptions, diagrams, etc. under an individual action.
Okay, thanks! I may not be remembering correctly, but I know that we at first provided a way to add "action details" via markdown when there wasn't a way to extract that information from the schemas. That remained for awhile, but I don't think anyone was using it and it was an either/or thing -- I'm not sure what would have taken precedence if you supplied markdown and also had the action information in the schema file. So I'd dropped that when we moved to the reworked config files.
It sounds like what you want is the same thing we have for Property Details, which is not all that complicated!
Added in action_details and merged.