From afb0a6b54bf95888625d5dd121662c4e46e45518 Mon Sep 17 00:00:00 2001 From: Liu YongLiang Date: Mon, 21 Feb 2022 22:38:15 +0800 Subject: [PATCH 1/4] update devGuide --- docs/devGuide/design/projectStructure.md | 19 ++++++++++--------- docs/devGuide/workflow.md | 16 ++++++++++++++++ 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/devGuide/design/projectStructure.md b/docs/devGuide/design/projectStructure.md index cab357eda4..6887dddddc 100644 --- a/docs/devGuide/design/projectStructure.md +++ b/docs/devGuide/design/projectStructure.md @@ -16,7 +16,7 @@ This page gives you an overview of the MarkBind's internal project structure. ## Packages -The MarkBind project is developed in a monorepo ([MarkBind/markbind](https://github.com/MarkBind/markbind)) of 4 packages: +The MarkBind project is developed in a monorepo ([MarkBind/markbind](https://github.com/MarkBind/markbind)) of 4 packages: * The core library, which parses and processes MarkBind's various syntaxes, resides in the `packages/core/` directory. @@ -32,29 +32,30 @@ The MarkBind project is developed in a monorepo ([MarkBind/markbind](https://git **The core library mainly houses:** -1. Functions and libraries used to parse and process MarkBind into usable output are stored in `src` The architecture described in [Architecture](../design/architecture) is contained here. A brief rundown of what it includes: +* Functions and libraries used to parse and process MarkBind into usable output are stored in `src`. The architecture described in [Architecture](../design/architecture) is contained here. A brief rundown of what it includes: * Various key functionalities in processing MarkBind syntax into valid html output, stored in `html`. The other part of the content processing flow is found in `variables`, which manages site variables and facillitates the Nunjucks calls. * `Page` files generate a single page of the site, and are managed by the `Site` instance. `Site` uses the Page model's interface to generate pages, and performs various other utility-like functions related to site generation such as copying of external assets into the output folder. * `Layout` holds the files relating to the layout of the site and are managed by `LayoutManager`. Similarly, `External` files, which are separate output files to be loaded dynamically and on-demand, are managed by a `ExternalManager` instance. * Various libraries (contained in `lib`) and plugins (in `plugins`) are also stored here. Some external libraries have also been amended to suit Markbind's purpose – see `patches`. - -1. MarkBind's [templates](https://markbind.org/userGuide/templates.html), used in the `markbind init` command. - -1. Unit Tests (though there are more unit tests and functional tests in the cli library) +* MarkBind's [templates](https://markbind.org/userGuide/templates.html), used in the `markbind init` command. +* Unit Tests (though there are more unit tests and functional tests in the cli library) **The key external libraries used are:** * [markdown-it](https://github.com/markdown-it/markdown-it), which does the Markdown parsing and rendering. There are also several customized markdown-it plugins used in MarkBind, which are located inside the `src/lib/markdown-it/` directory. - + * Serveral markdown-it plugins are installed to enhance the existing Markdown syntax. They can be found in `src/package.json`. Some of them are patched in the `src/lib/markdown-it/patches/` directory to fit MarkBind's needs. + * Additionally, there are some markdown-it plugins in the `src/lib/markdown-it/plugins/` directory (either forked, modified or written to enhance existing functionalities). * [htmlparser2](https://github.com/fb55/htmlparser2), a speedy and forgiving html parser which exposes a dom-like object structure to work on. To comply with the markdown spec, and our custom requirements, `src/patches/htmlparser2.js` patches various behaviours of this library. - * [cheerio](https://cheerio.js.org/), which is a node.js equivalent of [jQuery](https://jquery.com/). Cheerio uses [htmlparser2](https://github.com/fb55/htmlparser2) to parse the html as well, hence our patches propagate here. +* [Nunjucks](https://mozilla.github.io/nunjucks/), which is a JavaScript templating engine. Nunjucks is used to support our variable system to help with reusing small bits of code in multiple places. The package is patched and stored in `src/patches/nunjucks` to make it compatible with other MarkBind syntax processing steps. ### MarkBind CLI The CLI application uses and further builds on the interface exposed by the core library's `Site` model to provide functionalities for the author, such as `markbind serve` which initiates a live reload workflow. -The CLI program is built using [commander.js](https://github.com/tj/commander.js/). +**The key external libraries used are:** +* [commander.js](https://github.com/tj/commander.js/), which is a node.js CLI framework. +* [live-server](https://github.com/tapio/live-server), which is a simple web server for local development and preview of a MarkBind site. The package is patched and stored in `src/lib/live-server` with our custom fine tuning. ### MarkBind core-web library diff --git a/docs/devGuide/workflow.md b/docs/devGuide/workflow.md index 30bf7d6f63..e198c48b70 100644 --- a/docs/devGuide/workflow.md +++ b/docs/devGuide/workflow.md @@ -242,3 +242,19 @@ First, follow the instruction to [delete the dependency](#to-delete-a-dependency Dependency updates are not trivial, and can be the source of subtle bugs. You should always check the respective dependency changelogs before doing so! + +### Points for consideration +There are a few ways to incorporate external packages into MarkBind, each with its pros and cons. The following table shows some of the common trade-offs: + +Approach | Pros | Cons | +:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------| +Installing | | +Forking | | +Patching | | + +As the choice is highly dependent on context and details of the implementation, below are some additional questions to ask before proceeding: + +- Is the package actively maintained? +- How big is the package? +- How invasive are the proposed changes? +- Are there existing APIs/plugin system from the package (to modify default behaviors)? \ No newline at end of file From 4dc9049e3d360bd71a4facb97eea5bcdde352e25 Mon Sep 17 00:00:00 2001 From: Liu YongLiang Date: Tue, 22 Feb 2022 15:31:03 +0800 Subject: [PATCH 2/4] fix wording --- docs/devGuide/design/projectStructure.md | 2 +- docs/devGuide/workflow.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/devGuide/design/projectStructure.md b/docs/devGuide/design/projectStructure.md index 6887dddddc..60cb832fde 100644 --- a/docs/devGuide/design/projectStructure.md +++ b/docs/devGuide/design/projectStructure.md @@ -16,7 +16,7 @@ This page gives you an overview of the MarkBind's internal project structure. ## Packages -The MarkBind project is developed in a monorepo ([MarkBind/markbind](https://github.com/MarkBind/markbind)) of 4 packages: +The MarkBind project is developed in a monorepo ([MarkBind/markbind](https://github.com/MarkBind/markbind)) of 4 packages: * The core library, which parses and processes MarkBind's various syntaxes, resides in the `packages/core/` directory. diff --git a/docs/devGuide/workflow.md b/docs/devGuide/workflow.md index e198c48b70..d83ae0f9f4 100644 --- a/docs/devGuide/workflow.md +++ b/docs/devGuide/workflow.md @@ -250,7 +250,7 @@ Approach | Pros :-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------| Installing | | Forking | | -Patching | | +Patching | | As the choice is highly dependent on context and details of the implementation, below are some additional questions to ask before proceeding: From 0e0be18ae3f75ba9a6189b2f0e11a6465abbc14e Mon Sep 17 00:00:00 2001 From: Liu YongLiang Date: Tue, 22 Feb 2022 19:22:27 +0800 Subject: [PATCH 3/4] update spacing --- docs/devGuide/design/projectStructure.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/devGuide/design/projectStructure.md b/docs/devGuide/design/projectStructure.md index 60cb832fde..e03df789d5 100644 --- a/docs/devGuide/design/projectStructure.md +++ b/docs/devGuide/design/projectStructure.md @@ -33,20 +33,31 @@ The MarkBind project is developed in a + +Find out more about the key external libraries used in MarkBind from the [project structure](design/projectStructure.md) section. Also, the rationales behind most existing patches are documented in their respective files, read them (and their respective PRs/issues) for more context! + \ No newline at end of file