Add Markdown Linter Action/Config for Standardization

[Tbusk]

Description

Since markdown is quite flexible, perhaps it would be useful to add a linter to push for a more consistent markdown style.

Some editors for markdown have linters installed (neovim with markdownlint-cli2) which would benefit from following a linter standard.

It may be beneficial in some editors and for consistency, but it also may increase friction to add to the docs.

Additional Resources

• https://github.com/DavidAnson/markdownlint-cli2-action
• https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#configuration

[colinkiama]

Yes, I’m also a fan of this idea

[colinkiama]

I'm currently trying out markdownlint in my code editor (Sublime Text) now. I'm happy with the way it's working and with the default rules.

So I think that adding the markdownlint-cli2 GitHub action in pull requests to the main branch is good enough for now!

However, it has revealed a huge issue I missed regarding the table of contents in each section:

We're jumping from heading level 1 to level 4. Even in the generated HTML, this is something that we shouldn't be doing.

Another issue needs to be created for fixing the heading levels in these pages first before starting work on this issue.

[Tbusk]

Here is an idea I had for linting of the vala snippets:

write a small github action (or step) that collects all of these snippets by iterating over each .md file in the pr searching for vala markdown code block with regex and passing them to the existing vala linter as a new file.

A downside to this is that the code blocks likely need to all be valid. Some of the existing ones are shortened for brevity.

[colinkiama]

Oh regarding listing the Vala snippets, we may be able to do this more elegantly by moving the Vala snippets into their own files the importing them in documentation pages https://vitepress.dev/guide/markdown#import-code-snippets

We then should be able to easily execute Vala-lint in a /snippets directory for example.

[Tbusk]

Oh regarding listing the Vala snippets, we may be able to do this more elegantly by moving the Vala snippets into their own files the importing them in documentation pages https://vitepress.dev/guide/markdown#import-code-snippets

We then should be able to easily execute Vala-lint in a /snippets directory for example.

True, although I was also referring to pretty much anything in a md vala code block like this

vala-docs/docs/tutorials/programming-language/main/02-00-basics/02-06-control-structures.md

Lines 10 to 12 in 185cdac

	```vala
	do { a--; } while (a > b);
	```

rather than just something like

vala-docs/docs/tutorials/gui-programming/gtk4-samples/basic-app.md

Lines 5 to 32 in 185cdac

	```vala
	// BasicApp.vala
	public class BasicAppSample : Gtk.Application {
	public BasicAppSample () {
	Object (application_id: "com.example.BasicAppSample");
	}
	public override void activate () {
	var window = new Gtk.ApplicationWindow (this) {
	title = "Basic GTK4 App"
	};
	var button = new Gtk.Button.with_label ("Click me!");
	button.clicked.connect (() => {
	button.label = "Thank you";
	});
	window.child = button;
	window.present ();
	}
	public static int main (string[] args) {
	var app = new BasicAppSample ();
	return app.run (args);
	}
	}
	```