fix: Markdownlint

[bcronin90]

Fix markdownlint issues

Closes #692

MD053 in adoption-view.md looks like a false positive to me.

[stephanbcbauer]

LGTM, but please check if the title or id is used for header generation. THX

[mhellmeier]

The build of the website fails which should be fixed before merging.

[stephanbcbauer]

@bcronin90 the page can't be built, cause in the sidebarsDocsKits.js you reference to files/ids which are not present right now

Error:  Error: Invalid sidebar file at "sidebarsDocsKits.js".
These sidebar document ids do not exist:
- kits/Connector Kit/Development View/specifications
- kits/Connector Kit/Operation View/operation-view

Two options, rename the ids in the related files or change the reference. I think the ID itself shouldnt be changed, cause it is used for the headline?

[bcronin90]

The "title" field is used for the headline, which is why it caused duplication warnings in the linter. The "id" field is purely for under-the-hood stuff. While I was removing the titles, I added ids where there weren't any. Apparently that broke something somewhere. So I'll revert that.

[bcronin90]

So about this one:

docs-kits/kits/Connector Kit/Adoption View/adoption-view.md:152:1 MD053/link-image-reference-definitions Link and image reference definitions should be needed [Unused link or image reference definition: "dsp-url"] [Context: "[dsp-url]: https://docs.intern.../"]

Turns out it's not a false positive, just a bit misleading. We had a wrong bracket type in there. Yay for linting.

[bcronin90]

Okay, all Markdown errors should be from outside our scope now.

[stephanbcbauer]

Okay, all Markdown errors should be from outside our scope now.

@bcronin90 I built the page locally and i am not sure if this is related to the changes with the IDs, but the architecture page shows the headline twice

Definitely, this has nothing to do with the markdown :)

[bcronin90]

Might be something in one of the sidebars js'

[mhellmeier]

This PR removes the title in different files. Therefore, it doesn't get displayed with an uppercase starting letter. This has nothing to do with the sidebar file.

[bcronin90]

This PR removes the title in different files. Therefore, it doesn't get displayed with an uppercase starting letter. This has nothing to do with the sidebar file.

So what's the best practice here? Cause if I add it again, I get the duplicate header warning from the markdown linter, which this was supposed to remove. I can remove the actual markdown header instead. But instead of stumbling in the dark some more, I'll just ask: What's our general approach here?

[mhellmeier]

I suggest having a look at all the other KITs. Most KITs (what I would suggest) are using title along with id and description. Example from the Traceability KIT:

id: Architecture View Traceability Kit
title: Architecture View
description: 'Traceability Kit'
sidebar_position: 2

Please keep in mind to use a unique ID (not just Architecture), otherwise the build won't work.

[stephanbcbauer]

Not sure, is there still something todo here?

[mhellmeier]

The current branch can't be merged because the "Verify website build" stage is still failing.

[bcronin90]

Ah. I wasn't aware we explicitly linked each document again. I'll fix those links.

[mhellmeier]

Thanks for the fix!

[stephanbcbauer]

LGTM