Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Suggestion: Custom footer string #2559

Closed
nicfv opened this issue Apr 27, 2024 · 11 comments · Fixed by #2562
Closed

Suggestion: Custom footer string #2559

nicfv opened this issue Apr 27, 2024 · 11 comments · Fixed by #2562
Labels
enhancement Improved functionality good first issue Easier issue for first time contributors help wanted Contributions are especially encouraged
Milestone

Comments

@nicfv
Copy link

nicfv commented Apr 27, 2024

Search Terms

custom, footer, string, hide, generator

Problem

By using the --hideGenerator option, the message "created by TypeDoc" is removed, but the footer is still there. It might be nice to include an option to customize what is written in the footer instead.

Suggested Solution

--footer "<span class="...">should support html</span>"

@nicfv nicfv added the enhancement Improved functionality label Apr 27, 2024
@Gerrit0 Gerrit0 added help wanted Contributions are especially encouraged good first issue Easier issue for first time contributors labels Apr 27, 2024
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Apr 27, 2024

Sure, seems like an easy customization to allow

@Aryakoste
Copy link
Contributor

Hello @Gerrit0. I would like to work on this issue.

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Apr 28, 2024

Go for it!

@xuhdev
Copy link
Contributor

xuhdev commented Apr 28, 2024

There's already a plugin for this: https://typedoc-extra-footer.8hob.io/

@mayank1513
Copy link

There's already a plugin for this: https://typedoc-extra-footer.8hob.io/

Please don't avoid adding any features because there is a plugin. Plugins don't work with all versions of Typedoc

@xuhdev
Copy link
Contributor

xuhdev commented May 1, 2024

I don't oppose adding this feature to typedoc. Although architecture-wise I think typedoc should leave these kinds of specialized theme customization options to plugins, even as builtin ones. This is because this feature can be implemented seamlessly with only the hooks exposed to plugins, and doing so can avoid bloating the host system. (I'm happy to adapt the plugin above to a typedoc's builtin plugin, if you think desire.)

As the author of the plugin, with bias, I think the behavior defined in the plugin above is better designed (so I recommend a similar design in the implementation). Specifically,

  • If the custom footer and --hideGenerator are both specified, don't hide the custom footer. Instead, add the custom footer after the generator text.
  • Wrap the customer footer with a styled <p> tag if the user specified footer is not HTML. This permits users with not much HTML and CSS knowledge to use without struggling making the footer look reasonable.

What do you think? I kinda dislike the situation in which the plugin offers a minor advantage when the host system already offers the core features, so I'm striving to improve the situation so that I can abolish the plugin altogether. 😂

@mayank1513
Copy link

I am more interested in adding markdown pages to the documentation.

As of now, I just employed a quick hack - https://react18-tools.github.io/react18-global-store/

But, I believe that this is a very important part of documentation and should be supported by the library.

@Gerrit0
Copy link
Collaborator

Gerrit0 commented May 5, 2024

In general, I agree with @xuhdev, the more specialized functionality I can push to plugins, the easier to maintain TypeDoc itself stays, which makes it easier to maintain. I also mostly agree with the builtin plugin approach, though unfortunately it is messier than I'd like due to other constraints (options are all declared in one place for TypeDoc so that http://typedoc.org/schema.json can be easily generated, in 0.26 option descriptions are translated, and I'd really like to not spread the translatable strings all over the place to make it easier for translators)

That said, having worked places where getting plugins for approved software was a nightmare, I think it's important that it be easy to customize TypeDoc without requiring a plugin for everything. This is why the --customCss option exists, despite being easily implemented with a plugin.

I don't love making one option's behavior dependent on another option, as is done in typedoc-plugin-extra-footer, but can't argue with the improved user experience regarding adding the <p> wrapper...


@mayank1513 see #2567

@Gerrit0 Gerrit0 added this to the v0.26.0 milestone May 5, 2024
@Gerrit0 Gerrit0 mentioned this issue May 5, 2024
7 tasks
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jun 16, 2024

Included in TypeDoc 0.26, which is releasing 2024/06/21

@Gerrit0 Gerrit0 closed this as completed Jun 16, 2024
@mayank1513
Copy link

Can you also explain how to use this feature.

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jun 17, 2024

Exactly as proposed in your original post, with the option name customFooterHtml

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality good first issue Easier issue for first time contributors help wanted Contributions are especially encouraged
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants