Attempt to enable inclusion of partial markdown #227

ycmjason · 2018-04-23T21:08:54Z

Very unstable, need more advice

I have attempted to add this functionality as discussed in #222.

Current implementation facilitates the below functionality:

Replaces  with the content of the file (recursively)
Hot module reloading of dependencies

There are currently 2 known problems in this implementation:

Do not utilise the cache properly, files are being read multiple times even when no content is changed. (Slow down the build process.)
- Maybe I could create another cache in mdExplodeIncludes()
 could not be escaped even in code block. If PATH is an actual file, the file content would be used. This behaviour might not be desirable in some occasion. (e.g. when I was documenting about this functionality.)
- Not sure how should I determine when to escape...

ulivz

LGTM, only some small things.

ulivz · 2018-04-24T08:57:17Z

lib/webpack/util.js

+  const deps = []
+
+  return {
+    explodedSrc: src.replace(/<!-- *include +(.*?) *-->/g, (match, path) => {


Using  or  will be matched

Good idea. 🎉

ulivz · 2018-04-24T09:01:29Z

lib/webpack/util.js

+    explodedSrc: src.replace(/<!-- *include +(.*?) *-->/g, (match, path) => {
+      try {
+        const absolutePath = resolve(cwd, path)
+        const content = readFileSync(absolutePath, 'utf8')


Using a unified convention at the same project. either that all are await readFile or all are readFileSync

I have made this loader asynchronous. And it took me a really really long time to complete the asyncReplace function. I am so glad that I did this in such an elegant way.

Also it took me really long to debug the async loader as I forgot to call the callback when the loader hit the cache. 😭

Anyhow, it is using readFile now.

ulivz · 2018-04-24T09:05:19Z

lib/webpack/markdownLoader.js


 const cache = LRU({ max: 1000 })
 const devCache = LRU({ max: 1000 })

 module.exports = function (src) {
+  const file = this.resourcePath
+  const cwd = path.dirname(file)


just leverage dir

Can you explain more on this?

yyx990803 · 2018-04-24T21:38:17Z

lib/webpack/util.js

@@ -0,0 +1,49 @@
+const { promisify } = require('util')


You can use fs-extra here without having to promisify.

Oh, didn't know it exists. I will do this now.

ycmjason · 2018-04-24T21:52:20Z

@yyx990803 @ulivz
I would need more advice from you guys as mentioned in the main thread. 😀

Do you guys think those are big concerns?

Furthermore, one more thing to consider, should we force every partial to end with .partial.md and avoid vuepress from rendering a page for it? As discussed in #222.

ycmjason · 2018-04-27T20:30:29Z

lib/webpack/markdownLoader.js

+module.exports = async function (src) {
+  const cb = this.async()
+  try {
+  /* IMPORTANT: I didn't indent these lines to hopefully get a better looking diff */


I have un-indented the lines in the try { ... } catch block to show a better looking diff. Please re-indent when PR is accepted. 😊

ycmjason · 2018-04-27T21:08:03Z

Regarding the caching problem, after some think about it, it is probably not a problem because a partial is expected to be part of a longer markdown, therefore each partial should be included only once. 🌮

…de-md-includes

…cludes

kevinmpowell · 2018-06-05T19:25:04Z

Any idea on when this is going to be released? I'm working on a team that could really use this functionality.

ycmjason · 2018-06-05T19:50:19Z

@kevinmpowell
You can find the roadmap here. #421

Hopefully this will get released in 1.0.

…de-md-includes

ycmjason · 2018-08-08T18:40:10Z

@davemacdo @MartinMuzatko
Hello, I just came back from holidays. And I think you made a legit point. I personally quite like the syntax:

<<[path/to/file.md]

But I guess I will not make the changes to this PR unless @ulivz agree to it. 👍

songololo · 2018-10-20T14:22:43Z

Out of curiosity - how would partial markdown files work in regards to front-matter. Would each partial share access to the parent markdown's front-matter, or would each partial have its own front-matter?

I like the latter, because then it would be possible to have a separate markdown file for each method in package documentation, such that it is possible to define (in the each partial's front matter) the method name, parameter names and types, return names and types, etc, then render to an automated vue component. This would make for much cleaner and easier to read documentation code that could then also be automatically parsed from raw code, e.g. python docstrings, into markdown docs...

dovy · 2019-03-16T13:34:30Z

Any progress on this?

timaschew · 2019-03-23T21:18:31Z

@ycmjason

Since there is a similar syntax already to include code snippets which is

<<< @/filepath

it would be nice to have something similar to include markdown files.

But since v1 is not stable yet this can also be changed later (in another PR), right?

In general I like the approach of using a syntax which works when the markdown is rendered also on GitHub. It allows really easy contribution. Here is an example:

Open this page: https://docs.microsoft.com/en-us/azure/virtual-machines/linux/tutorial-manage-vm
Click on the Edit button
Spot the [!INCLUDE cloud-shell-try-it.md] in the rendered markdown. You can click on it and you'll be able to edit that file.

The syntax they use is:

[!INCLUDE [cloud-shell-try-it.md](../../../includes/cloud-shell-try-it.md)]

related: #1474

timaschew · 2019-03-24T15:28:43Z

Does the current implementation allow to include markdown files which itself have references to other resources, like links to other markdown files and images (or even nested includes)?

aliniacb · 2019-05-29T09:17:08Z

We can use the markdown-it-include plugin to achieve this. The only issue is the rebuild process. I have opened an issue here

ycmjason mentioned this pull request Apr 23, 2018

Markdown component #222

Closed

ycmjason force-pushed the explode-md-includes branch from fff62f3 to 4416673 Compare April 23, 2018 21:10

ulivz reviewed Apr 24, 2018

View reviewed changes

ulivz added the semver: minor label Apr 24, 2018

yyx990803 requested changes Apr 24, 2018

View reviewed changes

ycmjason added 4 commits April 27, 2018 21:17

added explosion of md includes

7d1a388

updated regexp

1362a90

made file reading async

b967b75

use fs-extra

43c760b

ycmjason force-pushed the explode-md-includes branch 2 times, most recently from 199f99e to d1c0da8 Compare April 27, 2018 20:27

try unindent lines for diff

961eada

ycmjason force-pushed the explode-md-includes branch from d1c0da8 to 961eada Compare April 27, 2018 20:28

ycmjason commented Apr 27, 2018

View reviewed changes

ycmjason added 2 commits April 27, 2018 21:31

added comment

3eaf157

added comment

4b5a3ab

ycmjason added 2 commits April 27, 2018 22:13

cwd to dir

61ac480

Merge branch 'master' of https://github.com/vuejs/vuepress into explo…

f30264d

…de-md-includes

ycmjason mentioned this pull request May 10, 2018

Require json dynamically and syntax highlight #393

Closed

ulivz mentioned this pull request May 11, 2018

[Roadmap] #421

Closed

ulivz added 1.0.0 and removed semver: minor labels May 13, 2018

ycmjason added 2 commits May 16, 2018 07:50

Merge branch 'master' of github.com:vuejs/vuepress into explode-md-in…

180caff

…cludes

Merge branch 'master' of github.com:vuejs/vuepress into explode-md-in…

2961060

…cludes

Merge branch 'master' of https://github.com/vuejs/vuepress into explo…

04785a8

…de-md-includes

ycmjason force-pushed the explode-md-includes branch from 51da635 to 63d755e Compare June 6, 2018 16:58

ulivz force-pushed the master branch 3 times, most recently from c992e38 to c2eaff3 Compare July 12, 2018 18:01

ulivz force-pushed the master branch 4 times, most recently from 0c3bc3a to cf1e6fc Compare July 28, 2018 08:12

ulivz force-pushed the master branch from 497a12b to f9de5e2 Compare August 9, 2018 16:57

ulivz removed the 1.0.0 label Aug 20, 2018

ulivz force-pushed the master branch 2 times, most recently from bd69d41 to 903138e Compare October 3, 2018 22:21

ulivz force-pushed the master branch 2 times, most recently from 3f79224 to fb05066 Compare October 23, 2018 15:09

ulivz force-pushed the master branch from d2ea14b to 5918ca9 Compare November 7, 2018 18:31

ulivz force-pushed the master branch from f339016 to ef4c7ec Compare November 25, 2018 12:10

ulivz force-pushed the master branch 3 times, most recently from 6c3127f to 71574f2 Compare December 18, 2018 18:27

ulivz force-pushed the master branch 5 times, most recently from 316e022 to 1284944 Compare January 29, 2019 11:47

ycmjason closed this May 29, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Attempt to enable inclusion of partial markdown #227

Attempt to enable inclusion of partial markdown #227

ycmjason commented Apr 23, 2018 •

edited

Loading

ulivz left a comment

ulivz Apr 24, 2018

ycmjason Apr 24, 2018

ulivz Apr 24, 2018

ycmjason Apr 24, 2018 •

edited

Loading

ulivz Apr 24, 2018

ycmjason Apr 24, 2018

yyx990803 Apr 24, 2018

ycmjason Apr 24, 2018

ycmjason commented Apr 24, 2018 •

edited

Loading

ycmjason Apr 27, 2018

ycmjason commented Apr 27, 2018

kevinmpowell commented Jun 5, 2018

ycmjason commented Jun 5, 2018

ycmjason commented Aug 8, 2018

songololo commented Oct 20, 2018

dovy commented Mar 16, 2019

timaschew commented Mar 23, 2019

timaschew commented Mar 24, 2019

aliniacb commented May 29, 2019

Attempt to enable inclusion of partial markdown #227

Attempt to enable inclusion of partial markdown #227

Conversation

ycmjason commented Apr 23, 2018 • edited Loading

ulivz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ycmjason Apr 24, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ycmjason commented Apr 24, 2018 • edited Loading

Choose a reason for hiding this comment

ycmjason commented Apr 27, 2018

kevinmpowell commented Jun 5, 2018

ycmjason commented Jun 5, 2018

ycmjason commented Aug 8, 2018

songololo commented Oct 20, 2018

dovy commented Mar 16, 2019

timaschew commented Mar 23, 2019

timaschew commented Mar 24, 2019

aliniacb commented May 29, 2019

ycmjason commented Apr 23, 2018 •

edited

Loading

ycmjason Apr 24, 2018 •

edited

Loading

ycmjason commented Apr 24, 2018 •

edited

Loading