Add example of content processing flow in developer documentation #2777
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2777 +/- ##
========================================
Coverage 71.67% 71.67%
========================================
Files 134 134
Lines 7284 7284
Branches 1607 1490 -117
========================================
Hits 5221 5221
Misses 2017 2017
Partials 46 46 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
Hi can I confirm that we're holding off from inserting any form of diagrams until PR #2775 is resolved? |
Feel free to add diagrams, #2775 should hopefully be a pure refactor that does not cause any functional changes! Also no change to the docs so won't have merge conflicts, unless you are worried about the processing flow and specific class names then can maybe wait a bit. Feel free to leave a PR review on my PR too 😄 Also, you can take a look at the preview of the site here: @ https://deploy-preview-2777--markbind-master.netlify.app/devguide/design/architecture#demonstration I think the example added is quite nice. |
| ``` | ||
| Notice that `myVariable` is consumed and that the unordered list is expanded. | ||
|
|
||
| Next, the NodeProcessor converts Markdown to HTML: |
There was a problem hiding this comment.
perhaps can include more detail on how NodeProcessor works, e.g. The use of markdown-it and the custom syntaxes defined
can refer to packages/core/src/html/NodeProcessor.ts or this section on deepwiki
There was a problem hiding this comment.
Hmm I think I don't want to go too low-level, the section right after roughly shows how it's done (the switch cases match the custom syntax). Maybe I should just mention it uses markdown-it? Wdyt
There was a problem hiding this comment.
ya ig mentioning we are using markdown-it with some custom logic would be great. Personally I was most interested in finding out how the '.md' source files are transformed into html pages.
There was a problem hiding this comment.
I think the small incremental steps for this example @Harjun751 has provided already follows the architecture diagram which does already state that it uses markdown-it, but yea ig it wouldnt hurt to mention it again at the specific step to reiterate this point. Perhaps we can create another issue in the future which goes into greater detail about the lower level implementationr egarding what's going on at each stage by referencing this example provided 😃.
There was a problem hiding this comment.
@yihao03 the dev docs
https://markbind.org/devdocs/devGuide/design/projectStructure.html#markbind-core-library
does have some mention of the use of markdown-it, as well as the plugins and patches, and others such as htmlparser2, cheerio etc. Evidently, it might not be in the most discoverable location. At the same time, it's also probably because we don't have a full text search which we will hopefully implement soon.
Perhaps you could look into how to make integrate this with the details on how NodeProcessor works, and find a way to strike a good balance (not be too specific or granular to have to update any diagrams if refactoring or update or add features, yet be detailed enough to give new developers a good understanding of what's happening)
Can raise a new issue, but don't fret too much about it.
There was a problem hiding this comment.
Just fix a bit of the wording and I think we can merge it in!
Thank you @Harjun751 for your help on this and @MoshiMoshiMochi @yihao03 for your inputs!
|
Welcome, @Harjun751! 🎉 Thank you for your contribution to the MarkBind project! @gerteck, please remember to add @Harjun751 as an official contributor to our repository. See the full list of contributors here. ✨ |
|
@all-contributors please add harjun751 for doc |
|
I've put up a pull request to add @Harjun751! 🎉 |
4 participants
What is the purpose of this pull request?
Resolves #2229
Overview of changes:
Adds a small section at the bottom of the Architecture section of the Dev docs showing the steps of how a file is processed
Anything you'd like to highlight/discuss:
Open to changing phrasing/adding more details if required.
Screenshot of changes
Testing instructions:
Proposed commit message: (wrap lines at 72 characters)
Add content processing flow example in docs
Checklist: ☑️
Reviewer checklist:
Indicate the SEMVER impact of the PR:
At the end of the review, please label the PR with the appropriate label:
r.Major,r.Minor,r.Patch.Breaking change release note preparation (if applicable):