Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add linting for custom markdown syntax #15

Open
4 tasks
GuySartorelli opened this issue Nov 1, 2023 · 0 comments
Open
4 tasks

Add linting for custom markdown syntax #15

GuySartorelli opened this issue Nov 1, 2023 · 0 comments

Comments

@GuySartorelli
Copy link
Member

GuySartorelli commented Nov 1, 2023

Initial linting was added in silverstripe/developer-docs#11 but excluded linting our custom markdown.

We have custom markdown syntax as documented in extended markdown syntax.

These need to be linted to avoid potential rendering errors, such as using an invalid callout block text (e.g. > [!SOMETHINGINVALID], trying to add text on the same line as the callout block header, forgetting to add space around either of these blocks, or trying to use an option that doesn't exist for the children block.

Acceptance criteria

  • Callout blocks are linted
    • Must not have any content on the same line as the header
    • Header must be one of the ones documented on the contribution page
    • Callout blocks must not be added inside another callout block, or a blockquote
    • Check if they render correctly in a table - if they don't, they must not be added there either.
  • Children blocks are linted
    • Must have an empty line before and after the children block
    • Children block must not span multiple lines
    • Must not have any other content on the same line as the children block
    • No unnecessary spaces are inside the children block
    • No unexpected options are used inside the children block
    • Children blocks must not be added inside a callout block, a blockquote, a list, or a table (basically, these can't be inside any block element other than a paragraph)
  • relative links (i.e. links to additional docs pages) are linted
    • Always include a trailing slash (if there's an anchor, the trailing slash is before the anchor)
    • Always start from / or be at the same level as the current page (i.e. no ../my_page)
    • Page being linked to must exist
    • If there's an anchor, the anchor must exist on the page being linked to
    • No absolute URLs (unless we're explicitly intentionally linking to docs from a different version - those should use an HTML comment to skip the linting rule for that URL)
  • API links are linted
    • Don't use the shorthand [api:MyNamespace\MyClass] - always use [`MyClass`](api:MyNamespace\MyClass)
    • Validate the syntax for the api link is correct (e.g. use MyNamespace\MyClass->propertyName for properties and config - never MyNamespace\MyClass.configName)
    • No absolute URLs
    • code in the text part of the link has backticks (e.g. [MyClass](api:MyNamespace\MyClass) is invalid, use [`MyClass`](api:MyNamespace\MyClass) instead)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant