plugin-pages: @page for any file

[mokone91]

trafficstars

Hi! Is its possible to add a link to page for not described pages in config?

example: I want to add the link to my change-log file at the bottom of readme, i have around 40 packages and all of theme have readme and changelog files at the root. i do not want to discribe the whole pages tree..

[GerkinDev]

Hi there,

Well, I have more or less planned to add the concept of front matter similar to what can be done with some static side generators like hugo.

With such feature, you could specify a glob pattern to match pages, and specify the page infos (such as title or output) directly in the front matter. Menu/directory configuration (such as children output directory or upcoming options evoked in #100) might then be done in an optional config file in each directory.

If you have any proposal/suggestion, I'm all ears.

Yet, what you want requires a full rework of the pages building process, and is not really a top priority.

[GerkinDev]

I just thought that changelogs may be auto-generated & published in other tools (GitHub releases, npm tarball, whatever), and thus, adding a front-matter does not really fit.

In your case, I would think of something like:

{
    pages: [
        {match: './packages/*/CHANGELOG.md', template: {
            moduleRoot: true,
            title: "{{CURRENT_MODULE.NAME}}",
            children: [
                {source: "./CHANGELOG.md",title: "Changelog"}
            ]
        }}
    ]
}

This would be expanded as following:

{
    pages: [
        {
            moduleRoot: true,
            title: "@example/foo",
            children: [
                {source: "./CHANGELOG.md",title: "Changelog"}
            ]
        },
        {
            moduleRoot: true,
            title: "@example/bar",
            children: [
                {source: "./CHANGELOG.md",title: "Changelog"}
            ]
        },
    ]
}

---

You could even append README to every modules with such pattern, making @knodes/typedoc-plugin-monorepo-readmes redundant:

{
    pages: [
        {match: './packages/*/README.md', template: {
            moduleRoot: true,
            title: "{{CURRENT_MODULE.NAME}}",
            source: "./README.md"
        }}
    ]
}

What do you think ?

[mokone91]

Yeah! Perfect for me!) is there a way to include index inside module lvl pages tree?

[GerkinDev]

Could you please clarify what you want to do ?

[mokone91]

Im happy to use glob pattern in root config when be available!

It will be nice if i can include index block directly to module subtree, but i understand that it not related to current topic and pages plug-in. I subscribed to https://github.com/KnodesCommunity/typedoc-plugins/issues/109

Thanks!

[mokone91]

But, if we will use pages for readme - what we will see as module homepage? for example:

Now:
Module1 -> shows readme(monorepo-readme-package)
 - page1 -> shows page1 (pages-pachage)
 - page2 -> shows page2 pages-pachage)
Module2
  ...


Then:
Module1 -> ???
 - readme -> shows readme (pages-package with glob support)
 - changelog -> shows changelog (pages-package with glob support)
Module2
  ...

[GerkinDev]

As I mentioned above, glob patterns would be expanded to the non-glob format:

        {match: './packages/*/README.md', template: {
            moduleRoot: true,
            title: "{{CURRENT_MODULE.NAME}}",
            source: "./README.md",
            children: [
              { source: './CHAMGELOG.md', title: 'Changelog'}
           ]
        }}

This would expand to

Module1 -> shows readme in Module1 + normal index
 - Changelog -> shows changelog of Module1
 - ...
Module2 -> shows readme in Module2 + normal index
 - Changelog -> shows changelog of Module2
 - ...

Would that matches your expectations ? There would be an extra behavior, that merges deeply items, so that you could specify pages for modules both via glob expansion & explicitly like now

[mokone91]

Ahh, it's can be managed using moduleRoot: true, sorry miss that.

Yeah perfect! Thats exactly what I need.

[GerkinDev]

Yeah this option was introduced in 0.23.0, see the docs page.

Don't hesitate to suggest improvements to documentation

[mokone91]

Hi! can we also add ability to use fileName for page title somehow? So it can be something like

{
  match: './packages/*/README.md',
  template: {
    moduleRoot: true,
    title: "{{CURRENT_MODULE.NAME}}",
    source: "./README.md",
    children: [
      { source: './CHAMGELOG.md', title: 'Changelog'},
      { source: './pages/*.md', title: "{{FILENAME}}"}
   ]
}}

Not sure if its possible, but i want to achieve the ability to add any pages to any modules without adding extra configuration rows to root config

Or maybe we can allow to add config for module lvl config? something like https://typedoc.org/guides/monorepo/#typedoc-package-config

Thanks!

[GerkinDev]

Hi!

So, about the 1st point, implementation is mostly done and you'll be able to interpolate almost any field from the path matched, using lodash templates in which you'll be able to use various fields from matches (including parents in case of nested templates), and use any lodash methods and a couple of cherry picked functions such as path's basename, dirname and a few others. The only thing I haven't implemented yet is using functions in place of template, so that you could specify advanced logic in your typedoc config as long as it is a js file. Introducing this feature have caveats tough, because some options defaults cause quite counter intuitive behaviors. I'm still working on the backward compatibility.

About the config splitted across packages, you can already somewhat emulate that by requiring modules configs from your root typedoc.js and do your stuff there. Built in support of composite config is not that trivial when you check how typedoc works, but I'm thinking about it.

[mokone91]

Sounds great! I'm waiting impatiently) Regarding requiring modules configs - yeah this should work, then we need to modify root config each time when we add new package... I believe templates feature will solve my needs)

[GerkinDev]

You might use something like this:

// typedoc.js
module.exports = {
  pluginPages: {
    pages: readdirSync('packages').reduce((acc, pkg) => {
      return [
        ...acc,
        ...(require(resolve('packages', pkg, 'typedoc.js'))?.pluginPages?.pages ?? [])
      ];
    }, []),
  }
}

[mokone91]

Have modified your snippet to attach chengelogs if exists

const pagesTree = readdirSync('packages').reduce((acc, pkg) => {
  if (existsSync(`./packages/${pkg}/CHANGELOG.md`)) {
    const pkgName = require(`./packages/${pkg}/package.json`).name;
    acc.push({
      title: pkgName,
      moduleRoot: true,
      childrenSourceDir: '.',
      children: [
        {
          title: 'Changelog',
          source: 'CHANGELOG.md',
        },
      ],
    });
  }
  return acc;
}, []);

but this works only if i place CHANGELOG.md to 'pages' folder inside package, even when 'childrenSourceDir': '.'

My changelog file placed directly at package root..

Seems i miss something..

[GerkinDev]

Yes this is due to an option I'm about to deprecate. Please set the source option to ""

[mokone91]

yep, adding source: '' to root pages config make it work! thanks!

[GerkinDev]

Hi,

So, I thought I was pretty done with template nodes. But after updating the docs, I realized that the result was super verbose as you can see in this repository's configuration. You can see the draft documentation here.

So I decided to made the integration of this feature more SOLID by normalizing interfaces & facilitate further extensions.

That's why I decided to add the front-matter idea in the branch at the same time. By the way, having both globs & front matters would make the legacy declarative format almost useless; in most cases:

• either the MD file is rather standard (Readme, changelog, etc) and would totally fit glob expansion
• or it is a custom page, for which front-matter approach is probably easier to manage

It also gives me a nice occasion to think about how to inject theme-specific options along with pages, and rework validation.

I hope you'll understand and be patient. Cheers!

[GerkinDev]

Hey there,

Could you check out latest next version ? https://www.npmjs.com/package/@knodes/typedoc-plugin-pages/v/0.23.5-next.1

You'll find the documentation for the new loader I hope you'll like here: https://knodescommunity.github.io/typedoc-plugins/v0.23.5-next.1/pages/_knodes_typedoc_plugin_pages/managing-pages-menu-items/using-the-front-matter-loader.html

The documentation is still a bit lacking, but I'm working on it.