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 62.30% 62.30%
=======================================
Files 130 130
Lines 7184 7184
Branches 1580 1509 -71
=======================================
Hits 4476 4476
Misses 2644 2644
Partials 64 64 ☔ 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. |
docs/devGuide/design/architecture.md
Outdated
|
|
||
| 3. Having processed possibly conflicting Nunjucks and Markdown syntax, HTML is then processed last. | ||
|
|
||
| {% from "njk/common.njk" import previous_next %} |
There was a problem hiding this comment.
Move the buttons to the bottom of the page!
docs/devGuide/design/architecture.md
Outdated
| {{ previous_next('projectStructure', 'serverSideRendering') }} | ||
| {{ previous_next('projectStructure', 'serverSideRendering') }} | ||
|
|
||
| ## Demonstration |
There was a problem hiding this comment.
Since the other headings on the page are h3 (###), maybe let's stick to that.
Also, can give it a slightly more descriptive title i.e. demonstration of XXX
| ``` | ||
| 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 😃.
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 documentation
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):