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

feat(developer): package compiler should convert .md files to .htm at compile time 🎺 #9477

Open
mcdurdin opened this issue Aug 17, 2023 · 2 comments

Comments

@mcdurdin
Copy link
Member

mcdurdin commented Aug 17, 2023

Relates to #9351.

If any of the metadata fields ReadmeFile, LicenseFile, WelcomeFile (see #9478) are listed in a package, and the file it refers to is a .md file, then it should be converted to .htm during the package compile, and the kmp.json file should refer to the .htm, and only the .htm should be included.

Note: don't forget to check for filename conflict when renaming -- if there is also a license.htm in the file, that will cause grief. (Case insensitive comparison reqd)

Another set of questions about multi-file documentation:

  • how do we handle internal links between .md files in packages? Need to rewrite the links generated from the .md and build list of all .md files to convert from that?
  • if we rename arbitrary.htm (whether generated from arbitrary.md or not) to welcome.htm for WelcomeFile, for better backward compatibility, then links to arbitrary.htm from other documentation files would also need to be updated. Suggestion 1: copy to welcome.htm rather than rename?

Question: header and footer for the .htm, as the .md will only be the content.

This relates to the kmp info.description field, which is also .md, although inline and without header and footer. This particular field also disables inline html, but the isolated .md files should allow inline html.

@mcdurdin
Copy link
Member Author

Note for @keymanapp/developers: please do not attempt to consume LICENSE.md when found in a .kmp, even if we have .kmp files in the wild that have LICENSE.md files. We'll only start to present license metadata from packages once we implement this feature in the package compiler -- it is not appropriate for us to add Markdown parsers to the Keyman apps.

@keymanapp-test-bot keymanapp-test-bot bot changed the title feat(developer): package compiler should convert .md files to .htm at compile time feat(developer): package compiler should convert .md files to .htm at compile time 🎺 Sep 15, 2023
@mcdurdin mcdurdin modified the milestones: A17S22, A17S23 Sep 30, 2023
mcdurdin added a commit that referenced this issue Oct 8, 2023
Fixes #9478.

This adds a property WelcomeFile to .kps and kmp.json, which allows us
to move away from the hardcoded welcome.htm filename in the future, and
makes transform from Markdown (#9477) a simpler operation, and just
generally starts the cleanup of the messiness of hard-coded filenames.

The package compiler will fallback to injecting welcome.htm into this
property if (a) welcome.htm is present, and (b) the property does not
already have a value. This doesn't buy us much because we still need to
support welcome.htm for existing legacy packages, but does mean that
our .kmp package metadata will be more consistent for packages compiled
with 17.0+ compilers.
@mcdurdin
Copy link
Member Author

mcdurdin commented Oct 8, 2023

Additional design thought: we should make it possible to specify a single custom CSS for the .md files in the packages, and include a standard one in Keyman Developer. (If we tag the body of the generated files with readme, welcome, and license class names, the single .css could cover all three files easily enough.)

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