Enhancement: Keep comment

[mjy9088]

Is your feature request related to a problem? Please describe.
I put comments for readability in the front matter. modified by this extension, all comments gone! 🎉

Describe the solution you'd like
use yaml or similar package to keep comments

[estruyf]

Thanks @mjy9088 this is indeed a known issue. Unfortunatly, this is related to the YAML parser. The sample you provided is still going to give the same issue. The YAML parser will keep only the comments that were added before the front matter section.

I have just tested this by writing a parser based on the sample you gave me. My front matter looks as follows:

The parser returns:

Important: Notice the comment and commentBefore, both are null.

Went a bet further, and checked what it parsed, and unfortunately, it also removes the comments:

Info: This is the data map from all the front matter fields it parsed. I'm using 13. and get 13 back, but the three comments are just ignored.

If you know a way to handle this, feel free to suggest or contribute. I'm sure this issue can help others as well.

[mjy9088]

https://codesandbox.io/s/yaml-comment-test-jl08o

import YAML from "yaml";

const original = `
# This is YAML
---
title: YAML Test
slug: yaml-test
date: '2022-02-08T17:34:18.844Z'
lastmod: '2022-02-09T10:08:20.682Z'
tags:
  - 'lang:XML'
  # TODO: add more languages
  # this comment is ok also
  - Test
`;

const parsed = YAML.parseDocument(original);

const serialized = parsed.toString();

console.log(serialized);

output:

# This is YAML
---
title: YAML Test
slug: yaml-test
date: '2022-02-08T17:34:18.844Z'
lastmod: '2022-02-09T10:08:20.682Z'
tags:
  - 'lang:XML'
  # TODO: add more languages
  # this comment is ok also
  - Test

The parser looks fine.

---

Since I had previously used the comment-json module (almost same to using global JSON object), I expected that using the yaml module would also be straightforward.

...but now that I see it, using this module is not that simple 😢 it seems like a lot of changes are needed to use this module.

[estruyf]

This works, as you just parse it and go straight to a string again. The reason why it doesn't work that easy is that the front matter will get parsed to JSON, because of that the comments are removed.

Internally we use the parse method, and that does parsed.toJSON() on the parsed document and so it loses the comments.

[mjy9088]

how about using yawn-yaml module to serialize?

const fs = require("fs");
const YAWN = require("yawn-yaml/cjs");
const yaml = require("js-yaml");

const originalText = fs.readFileSync("./original.yml").toString();
const yawn = new YAWN(originalText);
const content = yaml.load(originalText);

const test = "[TEST] THIS CONTENT IS DYNAMICALLY ADDED! - "
const changedContent = {
  ...content,
  tags: [
    test + "add",
    ...content.tags.map((a, i) => i ? [test + "more", a] : a).flat(1),
    test + "tags"
  ]
};

yawn.json = changedContent;

console.log(yawn.yaml);

input:

# This is YAML
---
title: YAML Test
slug: yaml-test
date: '2022-02-08T17:34:18.844Z'
lastmod: '2022-02-09T10:08:20.682Z'
tags:
  - 'lang:XML'
  # TODO: Check this comment remains
  - Test

output:

# This is YAML
---
title: YAML Test
slug: yaml-test
date: '2022-02-08T17:34:18.844Z'
lastmod: '2022-02-09T10:08:20.682Z'
tags:
  - '[TEST] THIS CONTENT IS DYNAMICALLY ADDED! - add'
  # TODO: Check this comment remains
  - 'lang:XML'
  - '[TEST] THIS CONTENT IS DYNAMICALLY ADDED! - more'
  - Test
  - '[TEST] THIS CONTENT IS DYNAMICALLY ADDED! - tags'

[mjy9088]

The reason why it doesn't work that easy is that the front matter will get parsed to JSON, because of that the comments are removed.

comment-json stores comments to symbol properties, so I thought yaml works similar way too... This is what I thought wrong. sorry

+ yawn-yaml doesn't works same way as comment-json, sometimes buggy. but it seems OK to add/modify existing value only

[estruyf]

@mjy9088 I've been testing the dependency you mentioned. It turns out that when updating arrays or objects it still removes comments.

Screen.Recording.2022-02-16.at.17.32.40.mov