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

Wikidocs format tweaks #173

Open
infotexture opened this issue Jun 2, 2023 · 0 comments
Open

Wikidocs format tweaks #173

infotexture opened this issue Jun 2, 2023 · 0 comments

Comments

@infotexture
Copy link
Collaborator

An earlier version of the plug-in implemented support for a special input format="wikidocs" for compatibility with Markdown files from GitHub wikis.

This format is currently configured to accommodate several quirks in the way GitHub wikis expect Markdown files to be authored:

  • The topic title is derived from the filename, so no first-level heading is required
  • The first paragraph is used as the short description (like format="mdita")
  • Subheadings are treated as nested topics (like format="markdown")

We're currently using this format to single-source topics between several plug-in wikis and the DITA-OT docs. This use case reveals several issues that could be resolved by adjusting the wikidocs format configuration.

Support for extensionless link syntax

  • GitHub wiki prefers extensionless link syntax:
    • [schema]: Markdown-schema
  • DITA-OT requires the extension, complains otherwise:
    • [schema]: Markdown-schema.md
    • But GitHub displays links with .md extensions as raw Markdown

Could the LwDITA plug-in could be updated to handle extensionless link syntax, so links in this format could be treated as Markdown and converted internally to Markdown DITA topics, even if the .md extension is not supplied?

Render subheadings as sections

The current approach renders subheadings as nested topics, and treats the first paragraph of each as a short description, so the resulting topic appears to have multiple short descriptions, like in Markdown DITA syntax.

For this use case, it might be better to treat subheadings as sections (like format="mdita").

This would mean we'd need to restrict ourselves to only a single subheading level, but this should be a reasonable tradeoff.

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