VuePress VS typedoc

VuePress is a minimalistic Vue-powered static site generator optimized for technical documentation and websites with a focus on content. It is suitable for creating documentation websites, blogs, and other content-focused projects.

VuePress - when I searched if it's supporting what I want (conditional rendering), the first result is a bug issue opened 4 years ago, so it doesn't seem to be a good option.

I'm new to IA Writer, and I'm wanting to use it to draft posts for my Vuepress site.

VitePress is listed in the documents as VuePress' little brother, and it is built on top of Vite. For those that don't know Vite is a build tool that aims to provide a faster and leaner development experience for modern web projects so it might sense to pair it with a static site generator such as VitePress. One of the original problems with VuePress was that it was a Webpack app and it took a lot of time to spin up a dev server for just a simple doc. VitePress solves these problems with nearly instant server start, an on-demand compilation that only compiles the page being served, and lightning-fast HMR. Let's get started!

VuePress

Trying to help build a design system at work in my spare time; no clue if it will go anywhere but it’s fun regardless. I asked the Elm Slack group what the equivalent of React Storybook. Specifically, I wanted a way to build a documentation website like Vuepress with the ability to host native Elm code to showcase components. They pointed me to Elm Book. While Elm Book has built-in theming capabilities, I needed CSS control over my components. While they support elm-css, I wanted the ability to use TailwindCSS. The Elm libraries haven’t kept up with Tailwind’s changes, which is fine; writing raw Tailwind CSS on Elm HTML functions is easy and co-located with the component you’re styling.

Vuepress is a minimalistic static site generator with a Vue-powered theming system and a default theme that has been optimized for writing technical documentation.

Documentation generation from your compiled .d.ts with typedoc

JavaScript (TypeScript) ecosystem has various types of API docs generators. Maybe the most popular one is TypeDoc. While generating API docs itself is easy, hosting API docs is pretty hard. Publishing generated HTML to static hosting service like GitHub Pages is the method I adopted previously, but it's not an ideal solution because we can't view docs for older versions.

Firstly, install Typedoc using npm:

Background:The main bottleneck with the TypeDoc default theme especially for large projects is the verbose HTML for the left-hand navigation that linearly grows for each page based on the project size and consumes a massive amount of disk space; see this TypeDoc issue. The DMT caches the left-hand navigation HTML and dynamically creates a shared web component that is utilized across all pages only making a single copy of the navigation HTML. This reduces disk space utilization by up to 90% and also makes doc generation ~80% faster. I also include some style additions and replace the main search index generation using compressed MesssagePack instead of JSON which reduces the search index size by more than 90%.

While the Prim+RPC server is expected to be JavaScript, I'd like to support other languages through JSON Schema. I wrote a tool that translates TypeDoc comments into RPC-specific documentation. My plan is to turn this result into JSON Schema that can be served with the Prim+RPC server. This means you can get typed suggestions (for instance, from an IDE that understands JSON Schema) when writing requests in JSON files (I wrote a little about this here, still a WIP). From this, you could use your favorite HTTP client in the language of your choice, like but still benefit from having typed requests.

Docusaurus has a Typedoc plugin. Also there is a typedoc markdown plugin.

Finally, JSDoc can be used to generate documentation for your code using tools like JSDoc itself and TypeDoc. These tools generate HTML or Markdown documentation based on your JSDoc annotations, making it easier for others to understand how your code works and how to use it.