support for publishing standalone Markdown, static HTML, WebAssembly hosts

[jonsequitur]

Some aspects of the Try .NET Markdown format make the source Markdown file less than ideal for display directly within e.g. a GitHub readme.md:

• Empty code fences referencing a backing project. These are populated at runtime by dotnet try but other Markdown parsers will render them as empty. While the content writer can populate them by copy-pasting from the source project, we want to avoid this maintenance burden.

• 187: file-wide settings.

Additionally, we should support static site generators and content management systems by doing the Markdown-to-HTML conversion at publish time rather than expecting it to be done at runtime.

The following command line examples are just sketches. In all cases, new files are emitted to <output dir> and source Markdown files are left unchanged.

• [ ] dotnet try publish --format Markdown --interactive:false <output dir>:
  • Emits a Markdown file for each source Markdown file.
  • Populates code fences using the latest backing source in a format suitable for use as read-only, non-interactive documentation, e.g. in GitHub's readme or wiki.
• [ ] dotnet try publish --format Markdown --interactive:true <output dir>:
  • Emits a Markdown file for each source Markdown file.
  • Emits a Try .NET WebAssembly package, which contains a Blazor app capturing the backing project's NuGet dependencies.
  • Populates code fences using the latest backing source.
  • Replaces --project annotations with --package annotations referencing to the Try .NET WebAssembly package.
• [ ] dotnet try publish --format HTML --interactive:false <output dir>
  • Emits an HTML file for each source Markdown file.
  • Transforms Markdown, replacing code fences with Try .NET-attributed <pre><code> blocks containing the latest backing source.
• [ ] dotnet try publish --format HTML --interactive:true <output dir>
  • Emits an HTML file for each source Markdown file.
  • Creates a Try .NET WebAssembly package.
  • Transforms Markdown into HTML, replacing code fences with Try .NET-attributed <pre><code> blocks containing the latest backing source.
  • Replaces data-trydotnet-package attribute values with refences to the Try .NET WebAssembly package.

[akshita31]

This looks really good. A couple questions: What will be a general usage pattern for the publish step.

1. Like is it my responsibility as a content author that whenever I make some changes to my markdown file or to my backing project, I should run the command and then submit the PR ?
2. Or, it will be a task in the build pipeline that will execute everytime a PR is submitted ?

If we go for the first case then the things might go "off-sync". And in the second case,if there are any changes that need to be published, will the build system automatically create a PR for it or directly publish the changes somehow.

Not sure if we need to think this to that extent but I was just curious 🔢

[akshita31]

Also, we should start using "dotnet try verify" in our CI/CD pipeline for the samples or the docs folder so that we are able to have an example for others who might want to do the same.

[jonsequitur]

We do currently test this: https://github.com/dotnet/try/blob/b1b6dc73a1ef3f7186904251edfa635a903d5a6c/MLS.Agent.Tests/CommandLine/DemoCommandTests.cs#L28

[jimbobbennett]

dotnet try publish --format Markdown --interactive:false <output dir>:

• Emits a Markdown file for each source Markdown file.
• Populates code fences using the latest backing source in a format suitable for use as read-only, non-interactive documentation, e.g. in GitHub's readme or wiki.

Would love this. When publishing tutorials to GitHub it would be great if they were readable straight away without installing the tool and running it. Having it done automatically also makes this a great way to validate static code in tutorials or workshops - compile behind the scenes then auto-populate with working code as part of a CI/CD step in a PR.