From b7b2899e55e1804c3a58b258b8e1bb45d50bd9f1 Mon Sep 17 00:00:00 2001 From: Viktor Bahr Date: Thu, 14 Apr 2022 17:44:08 +0200 Subject: [PATCH 1/5] test(techdocs-node): sequence node custom tag validation failure This test proves that currently only scalar YAML nodes are considered valid by the mkdocs YAML validation logic, even though using the `!ENV` tag with sequential data is officially supported by mkdocs[0]. [0] https://www.mkdocs.org/user-guide/configuration/#environment-variables Signed-off-by: Viktor Bahr --- .../generate/__fixtures__/mkdocs_with_env_tag.yml | 1 + .../techdocs-node/src/stages/generate/helpers.test.ts | 11 ++++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml diff --git a/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml b/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml new file mode 100644 index 0000000000..8da1ef0cca --- /dev/null +++ b/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml @@ -0,0 +1 @@ +site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] \ No newline at end of file diff --git a/plugins/techdocs-node/src/stages/generate/helpers.test.ts b/plugins/techdocs-node/src/stages/generate/helpers.test.ts index 7590df94fb..f45f6034ec 100644 --- a/plugins/techdocs-node/src/stages/generate/helpers.test.ts +++ b/plugins/techdocs-node/src/stages/generate/helpers.test.ts @@ -78,6 +78,9 @@ const mkdocsYmlWithoutPlugins = fs.readFileSync( const mkdocsYmlWithAdditionalPlugins = fs.readFileSync( resolvePath(__filename, '../__fixtures__/mkdocs_with_additional_plugins.yml'), ); +const mkdocsYmlWithEnvTag = fs.readFileSync( + resolvePath(__filename, '../__fixtures__/mkdocs_with_env_tag.yml'), +); const mockLogger = getVoidLogger(); const warn = jest.spyOn(mockLogger, 'warn'); @@ -582,10 +585,16 @@ describe('helpers', () => { ).rejects.toThrow(); }); - it('should validate files with custom yaml tags', async () => { + it('should validate files with custom yaml tags (scalar)', async () => { await expect( validateMkdocsYaml(inputDir, mkdocsYmlWithExtensions.toString()), ).resolves.toBeUndefined(); }); + + it('should validate files with custom yaml tags (sequence)', async () => { + await expect( + validateMkdocsYaml(inputDir, mkdocsYmlWithEnvTag.toString()), + ).resolves.toBeUndefined(); + }); }); }); From 24db82d8c198298e2994b1c9281854261c131c24 Mon Sep 17 00:00:00 2001 From: Viktor Bahr Date: Thu, 14 Apr 2022 17:49:13 +0200 Subject: [PATCH 2/5] feat(techdocs-node): accept sequence node custom tags This change to the MKDOCS_SCHEMA lets the validation logic accept custom tags that are sequence nodes as valid. Signed-off-by: Viktor Bahr --- plugins/techdocs-node/src/stages/generate/helpers.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/techdocs-node/src/stages/generate/helpers.ts b/plugins/techdocs-node/src/stages/generate/helpers.ts index 349783d2bd..d70793e043 100644 --- a/plugins/techdocs-node/src/stages/generate/helpers.ts +++ b/plugins/techdocs-node/src/stages/generate/helpers.ts @@ -134,6 +134,14 @@ export const MKDOCS_SCHEMA = DEFAULT_SCHEMA.extend([ instanceOf: UnknownTag, construct: (data: string, type?: string) => new UnknownTag(data, type), }), + new Type('', { + kind: 'sequence', + multi: true, + representName: o => (o as UnknownTag).type, + represent: o => (o as UnknownTag).data ?? '', + instanceOf: UnknownTag, + construct: (data: string, type?: string) => new UnknownTag(data, type), + }), ]); /** From 5f5d9b19bc884c469af9c1ae1d6d3a2368b1070e Mon Sep 17 00:00:00 2001 From: Viktor Bahr Date: Thu, 14 Apr 2022 18:19:26 +0200 Subject: [PATCH 3/5] chore: add changeset Signed-off-by: Viktor Bahr --- .changeset/nice-boats-wonder.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/nice-boats-wonder.md diff --git a/.changeset/nice-boats-wonder.md b/.changeset/nice-boats-wonder.md new file mode 100644 index 0000000000..434cde841e --- /dev/null +++ b/.changeset/nice-boats-wonder.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs-node': patch +--- + +Allow usage of custom tags with sequence node type (such as the !ENV tag) in the techdocs mkdocs config. From 465c8770e54a44e351c38d6b878ac2836a868964 Mon Sep 17 00:00:00 2001 From: Viktor Bahr Date: Mon, 25 Apr 2022 10:58:01 +0200 Subject: [PATCH 4/5] fix(techdocs-node): add trailing newline to fixture Signed-off-by: Viktor Bahr --- .../src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml b/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml index 8da1ef0cca..cba0cd8373 100644 --- a/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml +++ b/plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_env_tag.yml @@ -1 +1 @@ -site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] \ No newline at end of file +site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name'] From b26f4cb6a192f2e01686954dffb93e6618575c91 Mon Sep 17 00:00:00 2001 From: Viktor Bahr Date: Mon, 25 Apr 2022 11:02:36 +0200 Subject: [PATCH 5/5] fix(changeset): add techdocs prefix to changeset As requested by reviewer @iamEAP Signed-off-by: Viktor Bahr --- .../{nice-boats-wonder.md => techdocs-nice-boats-wonder.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changeset/{nice-boats-wonder.md => techdocs-nice-boats-wonder.md} (100%) diff --git a/.changeset/nice-boats-wonder.md b/.changeset/techdocs-nice-boats-wonder.md similarity index 100% rename from .changeset/nice-boats-wonder.md rename to .changeset/techdocs-nice-boats-wonder.md