Is it possible to add more static pages to the generated web? And possibly improve the aesthetics?

[ilg-ul]

After successfully configuring my TypeScript projects to automatically generate the documentation sites with TypeDoc, and resulting sites like https://xpack.github.io/logger-ts/, I further pursued the idea and did the same for one of my C/C++ project, with Doxygen.

The site is not yet 100% ready, there are still some small issues, but the preliminary result looks like this:

The actual project URL is https://micro-os-plus.github.io/utils-lists-xpack/.

Personally I liked the result, to the point of deciding to migrate the entire documentation from the existing READMEs to the web site, as the static pages listed in the left sidebar.

A later improvement was the addition of the cards, as a nice solution for quick access to the most frequent pages.

I was wandering if now, when I have more experience with these things, perhaps I can achieve something similar with TypeDoc, and do a second iteration for my TypeScript projects to bring them in line with the C/C++ projects.

Any thoughts on this?

[krisztianb]

I think you can achieve something similar by defining a custom README via the TypeDoc options. From that file you should be able to link to other pages. However you won't be able to add custom links in the left column.

[ilg-ul]

I just noticed that the TypeDoc web site (https://github.com/TypeStrong/typedoc-site), which seems to be generated with TypeDoc itself, can display multiple entries in the sidebar, so it should be possible to achieve something similar to Doxygen.

Just that Doxygen with the custom theme looks really nice! ;-)

[krisztianb]

I think you are right. This plugin seems to do that: https://www.npmjs.com/package/@knodes/typedoc-plugin-pages

[Gerrit0]

This issue really highlights a difficult design decision for TypeDoc. There are two competing options, and I really haven't decided which one makes more sense in the long run.

1. TypeDoc should provide the means to generate an entire site for documentation (this is what Generate pages corresponding to Markdown files in directories #1870 is after)
2. TypeDoc should focus on generating API documentation that can be provided as input to another site generation tool.

These aren't necessarily mutually exclusive options (except for time -- I'd like to pick one, and focus on that, rather than spend time half supporting each), and both have advantages. The first is closer to what TypeDoc has historically done, and is really nice for quickly getting set up with a basic documentation site. The second explicitly focuses on enabling integration with other site generation tools, which is advantageous for sites which need longer form content that doesn't fit well in a comment, integration with a playground for experimenting with a library, and many other reasons...

@tgreyuk has done an incredible job with typedoc-plugin-markdown which better supports the second use case. It is no accident that roughly 25% of TypeDoc users don't use the HTML output, and integrate the markdown produced by typedoc-plugin-markdown into some other tool instead.

That percentage is high enough that it sometimes makes me think that TypeDoc should just be generating markdown, or even just output JSON along with maintaining plugins for other site generation tools built by people that actually know what they're doing for keeping track of multiple versions, documentation in different languages, etc. (Maybe the current default theme gets extracted into a "static site" consumer of the JSON for simple projects?)

[ilg-ul]

In case it helps, here is my recent experience.

Doxygen supported multiple static pages for long, but the poor aesthetics were a major factor in avoiding it as much as possible.

Now, after Doxygen got a nice theme, I'm migrating all my C/C++ projects from Jekyll + Doxygen to Doxygen only. It is much easier to maintain, and, why not recognise, it looks really nice and clean. And not only that a separate static site generator is no longer needed, but I also moved the project README, README-MAINTAINER and README-DEVELOPER from plain GitHub pages to Doxygen, and everything is in one place:

• https://micro-os-plus.github.io/utils-lists-xpack/

Then I'm considering to move the GitHub READMEs to the web for the TypeScript projects too and started this thread, to know your opinion.

As for the idea to turn everything into markdown and let another static site generator consume it, I don't have any experience with it, but I'm a bit concerned on the resulting aestehics.

Also from my recent experience, I searched for a solution to get rid of Jekyll & Ruby & bundler & Co, which I used for all my sites when I migrated to GitHub. After a very long search, I opted for Docusaurus, which, although it has a funny name, and its own site may look a bit childish, can generate very nice looking sites.

However, the problem is that Docusaurus is part of the React ecosystem, and markdown is not exactly GitHub markdown, it is in fact MDX, a relative of JSX, a syntax which is compiled into JavaScript. And there is no pre-processing step with a text based substitution engine like Liquid, all automation required by pages with configurable content is done within the limits of JavaScript code. The result is that Jekyll sites need a lot of manual rework to convert them to a MDX compliant syntax.

Thus, if I'd have to prioritise the two options, I'd vote for the first one, and focus on improving the aesthetics, for example by inspiring from the new Doxygen theme; once this is done successfully, sure, generating JSON or markdown can be further considered, but integrating into some other tools might not be trivial, plus that there are so many, and supporting all of them is not realistic.

There are plenty of small to medium projects that would benefit from having the entire documentation generated with TypeDoc alone, and do not need to use a separate static site generator.

[tgreyuk]

@Gerrit0 - Thanks for your ongoing investment in the project - it's very much appreciated.

There are two competing options, and I really haven't decided which one makes more sense in the long run.

1. TypeDoc should provide the means to generate an entire site for documentation
2. TypeDoc should focus on generating API documentation that can be provided as input to another site generation tool.

This is actually something I have been thinking about quite a lot recently as I am currently completely re-writing typedoc-plugin-markdown. Naturally from my point of view i'd be interested in exploring the second option, or at least proving a better mechanism to achieve this goal.

typedoc-plugin-markdown currently attempts to piggy-back onto TypeDocs Renderer class. This has sort of worked but has never felt quite 'correct' as the Renderer is very coupled to HTML output. Really i'd like to create a custom renderer without all the HTML noise (loading highlighters, jsx hooks, assets plugins etc).

I thought perhaps a base renderer class could be exposed that is completely decoupled from the type of generated output, that consumers could extended with a bespoke HTMLRenderer, MarkdownRenderer or whatever. Perhaps a renderer could be defined by a plugin and then applied at the bootstrap stage, or the DefaultRenderer HTML renderer would be used. I guess in a similar vain as to how the Theme model currently works.

The other option would be to break from the TypeDoc renderer completely and just consume the converted project and write a completely custom renderer. I'd prefer the former as the plugin remains aligned to the Renderer Event model.

Anyway I am not too sure what the best way forward but thought I'd throw in my two cents to get a conversation going. I'd be very happy to contribute too.

[ilg-ul]

Since this topic also discusses integration with another site generators, did anyone consider integration with Docusaurus?

For example how do you pass Admonitions, Tabs, and other such advanced features?

[Gerrit0]

I'm not entirely sure how it's been a full year since I last looked at this, but... I'm starting to take steps towards decoupling the idea of output from the renderer. #2597 has an outline of my first cut at what that might look like.

There are plenty of small to medium projects that would benefit from having the entire documentation generated with TypeDoc alone, and do not need to use a separate static site generator.

Ultimately, I agree with this. Architecturally, it'll probably end up split into a module that's only very lightly coupled, and could easily be lifted out into its own package if desired.

Anyway I am not too sure what the best way forward but thought I'd throw in my two cents to get a conversation going. I'd be very happy to contribute too.

Thanks! I'd really appreciate your thoughts on #2597

Since this topic also discusses integration with another site generators, did anyone consider integration with Docusaurus?

This is the emit markdown with typedoc-plugin-markdown and plug it into another generator approach! docusaurus-plugin-typedoc

For example how do you pass Admonitions, Tabs, and other such advanced features?

TypeDoc doesn't! In 0.26.0 (this Friday), TypeDoc swiches to markdown-it for markdown parsing, so now all of this is completely configurable at the user level markdown-it-admon could be added to the markdown renderer to customize the HTML output using the markdownItLoader option. A (very) quick google didn't reveal a tabs equivalent, but there's no reason that one couldn't be written by someone who really wanted that feature. DigitalOcean has built quite a few which show the flexibility of this system

---

I'm closing this issue as I've split out the renderer rework into another issue and the two questions originally posed are:

1. More static pages - added in 0.26
2. Improve the aesthetics - entirely too broad to be generally actionable... TypeDoc supports a --customCss option for local tweaks, and the markdown included may include HTML by default.... if you really wanted to, you could do cards with something like the following in TypeDoc today:

<div class="cards">
    <a class="card" href="https://example.com">
        <span class="card-title">Example</span>
        <p>Go here for all your example needs</p>
    </a>
    <a class="card" href="https://typedoc.org">
        <span class="card-title">TypeDoc</span>
        <p>Go here for all your documentation needs</p>
    </a>
</div>
<style>
    .cards {
        display: flex;
        justify-content: space-around;
    }
    .cards .card {
        text-decoration: none;
        display: block;
        border: 1px solid var(--color-accent);
        box-shadow: 0 0.2em 1em var(--color-accent);
        padding: 1em;
        color: var(--color-text);
        transition: box-shadow 0.2s;
    }
    .cards .card:hover, .cards .card:focus {
        box-shadow: 0 0.5em 1.5em var(--color-accent);
        border-color: var(--color-focus-outline);
    }
    .card .card-title {
        font-size: 2rem;
    }
</style>

Which renders as: