Add offline emulation of the site

[paultyng]

Ability to run something like tfplugindocs serve to browse the site locally.

[wjam]

Has any thought been given on how to implement this?

I've started putting something together that reuses https://registry.terraform.io/tools/doc-preview to avoid having duplicate implementations of the rendering of the markdown. While there are a number of things that still need to be done (mostly marked with TODO comments), would this be acceptable?

My implementation proxies requests to the doc preview page and injects enough JavaScript to show the page and support switching the content of the textarea to display the other pages.

https://github.com/wjam/terraform-plugin-docs/commit/c488aaff8ee280c3f7f7476edec2b42ec5a2a7a1

[dominik-lekse]

Found this gem while working on a terraform provider.

@wjam I really like the approach for the local preview to reuse the Terraform registry doc preview tool. It is a real time saver when reviewing the documentation.

When trying the implementation at https://github.com/wjam/terraform-plugin-docs/commit/c488aaff8ee280c3f7f7476edec2b42ec5a2a7a1, the browser debugger shows errors related to the X-Content-Type-Options header. I guess this is related to recent security enhancements in the browser.

Starting from https://github.com/wjam/terraform-plugin-docs/commit/c488aaff8ee280c3f7f7476edec2b42ec5a2a7a1, I added the following improvements and resolved some open TODOs:

• Use httputil.ReverseProxy in proxyRequest; this fixed the X-Content-Type-Options header violations mentions earlier
• Embed menu template and javascript using go:embed
• Added optional argument --addr [host:port]
• Moved serve related code from cmd to serve
• Find text area with query selector to avoid hard-coded id
• Rebase to current main

Checkout the improved tfplugindocs serve in https://github.com/dominik-lekse/terraform-plugin-docs/tree/serve-docs

@paultyng Do you have an update on the planing/roadmap of the preview feature?

The approach to inject javascript/markdown in the proxy is not ideal. However, it serves the purpose well as it includes a working navigation between resources and data sources like in the real terraform registry docs.

When going with the proxy approach, one direction could be to improve the registry doc preview tool to integrate nicer with the proxy (e.g. provide a javascript function to render the markdown to avoid the textarea injection).

A fully offline preview would of course require all assets of the preview tool to be embedded in tfplugindocs and would not need a proxy. At this point, I am not sure if the source of the registry doc preview tool is available to the public.

[spikewang]

This will be really helpful when developing provider. There are several use cases here:

1. We want to visualize and validate before publishing the new version of the provider to the registry... I could try to generate one website based on markdown, but it won't be always rendered the same as registry...
2. We want to host our internal documentation site to always point to the latest dev branch before publishing to registry. This will serve everyone internally who want to test the latest.