Embed all objects under a Module/Namespace onto single page

[lorenzolewis]

I see the undocumented flag allReflectionsHaveOwnDocument. Is there a way to extend this to also work for Enums, Classes, and Interfaces so that essentially everything under a module/namespace is all on a single page?

I moved around the objects here https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/packages/typedoc-plugin-markdown/src/theme.ts#L328-L338 but the resulting output just renders those more... complicated items as Object in the output.

I'm assuming this would have to adjust how the templates are structured. This is something I'm working on in my fork so happy for any advice on this and can open a PR once it's setup if you'd like.

[tgreyuk]

I have been looking at this on the next branch but haven't had time to bring it forward. The idea would be for user to specify what symbols to hoist onto a single page using a hasOwnDocument option. Experimental currently.

--hasOwnDocument
Determines which symbols should be hoisted to their own document. Expected values are None, All OR Array of ['class', 'interface', 'enum', 'function', 'variable', 'type'] Defaults to None (all symbols included in a single module page). 

The idea is that when the theme iterates over reflections from the model it would go through a mapping map in a similar way that the html theme does. https://github.com/tgreyuk/typedoc-plugin-markdown/blob/next/packages/typedoc-plugin-markdown/src/theme.ts#L194

Feel free to take a look, or even branch off the next branch as the architecture has changed a bit.

[lorenzolewis]

Ah, didn't see the next branch before, that's a pretty big refactor, looks exciting! 2 things:

1. Do you know very roughly when you're hoping to land it?
2. Is there anything I could do to help out on that because would much rather be able to contribute back to that to use it rather than try to back-deploy the work you've already done.

[tgreyuk]

:) i really want to get it out a.s.a.p but i haven't tested it enough and it all feels a bit exprimental. It would be fantastic to get another pair of eyes on it. There is no harm in pushing it out as a 4.0@beta and not advertise it. Id be interested what you think (sorry I haven't written any docs for it yet and the tests are probably all failing but i can look at that).

Main bits are:

• removed handlebars
• updated theming model to follow the html theme, which means each partial can be easily overridden
• updated directory structure to follow module structure
• ability to add all symbols into single doc
• some ui tweaks

[lorenzolewis]

A published beta would make testing a lot easier, local NPM packages are no fun especially when you attempt to make it work with CI :D

[lorenzolewis]

I've found one bug so far where urlTo is getting leaked out to the markdown for a few pages, not escaped, and then causing JSX to have fun. So can put in a proper issue for you once a beta is out and I'm using a less throw together fork on my end.

[lorenzolewis]

Two more bugs I've found:

1. If there is a comment for a return type it is no longer rendered:
   Before (with master):

After (with next):

2. There are some instances where context.indexSignaturePartial are in code as a string (in partials/member.declaration.ts:29, partials/reflection.ts:50, and templates/reflections.ts:49) and aren't being parsed correctly for the output:

More than happy to put in a PR for these if you have a quick direction for me to check out.

[lorenzolewis]

Put in a PR for the comment issue, not 100% sure if you'd like it solved that way but it's close to how the old impl was done.

I tried to dig into the indexSignaturePartial, but I'm liking the way it works now (when it works) in next instead of the old version. In the screenshot below, the old master impl just has Object on the args line, but I like how next has it written out (args: { [name: string]: ArgMatch;}).

[lorenzolewis]

@tgreyuk I've spent a good chunk of time the past few days getting the next branch up and running for our production site. I'd love to help get that branch closer to a release. Do you have anything I could help on to move that forward?

We also made some more subjective formatting changes that I feel could be good improvements, but not sure of the best way to discuss if those are things you'd like a PR, issue, etc. for or not.

[lorenzolewis]

@tgreyuk you mentioned about putting out a beta on NPM of next, is there anything I can do to push towards that and help out?

[tgreyuk]

Yeah - sorry. I was busy on something else but am now focussed on this project again. The branches have diverged quite a bit and i just need to make sure i've not lost anything in the transition.

…

On Sat, 3 Dec 2022 at 13:55, Lorenzo Lewis ***@***.***> wrote: @tgreyuk <https://github.com/tgreyuk> you mentioned about putting out a beta on NPM of next, is there anything I can do to push towards that and help out? — Reply to this email directly, view it on GitHub <#338 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACZDYZRT6N3XYWDT7MFJZCDWLNGL5ANCNFSM56QSEFMA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[balazsorban44]

I'm happy to test this out as well when/if ready!

I want to be able to have interfaces, type aliases, functions, parameters on the module page, instead of linking to a different one on authjs.dev. Currently, this is how it looks like: https://auth-docs-git-chore-reference-sidebar-authjs.vercel.app/reference/core/modules/jwt.

For now, I came up with a hack, but it is rendering titles a bit redundant, and interfaces are just Objects.

Disclaimer:
I am new to TypeDoc in general, but if I can help out with this in any way, let me know!

Great work! 💚

[balazsorban44]

I've been looking more into this lately, and I was checking out the next branch, it's exactly what I would like with the --symbolsWithOwnFile none flag! 🎉

Some feedback:

• The heading seems to be off, Functions and Interfaces got both h1, while the generated markdown file already has one title. So reflections(?) should be indented another level, starting with 2, and everything below needs to be bumped too.
• Not sure if this is something that needs fixing in the typedoc-plugin-markdown package, but we are trying to use the generated markdown files as MDX, and they have to unescaped characters, namely < and {. if these could be escaped by default, it would be nice, otherwise I can just patch it on our side.
• Would it be possible to get rid of the README.md file and the modules folder too, maybe via a config option? I would like it if the out dir had the contents of the modules directory and that's it (UPDATE: fileStructure: "modules" resolves the second part.)
• Is there a way to hide hierarchy sections?
• Is there a way to hide certain reflection headers? (I have a module that exports a bunch of classes only, and I do not need the "Classes" header

I am still happy to be an early tester, if you need help, let me know, and I would also like to sponsor you or the project if you accept it. 💚

[phaux]

Why doesn't --symbolsWithOwnFile none work on latest @next?

Edit: nvm I figured it out:

npx typedoc --plugin typedoc-plugin-markdown --readme none \
  --disableSources --hidePageTitle --hideBreadcrumbs --hideInPageTOC \
  --outputFileStrategy modules --excludeGroups \
  --propertiesFormat table --parametersFormat table \
  src/index.ts

very clean and readable output

[tgreyuk]

https://www.typedoc-plugin-markdown.org/docs/options#outputfilestrategy