[core] docLinks server-side service

[rudolf]

When converting the legacy ui/documentation_links to the new platform we built it as a browser-side only service to match the features of the legacy implementation.

However there are a number of places where we it would be helpful to be able to construct a message on the server-side to point users to our documentation e.g.:

• HTTP API Error responses
• Server error logs
• Deprecation logs

(This will probably also require updating the doc build script)

[pgayvallet]

I think the best place for the links currently living in src/core/public/doc_links/doc_links_service.ts would be a package.
Core's client and server-side service would just consume this list.

The doc build script will have to be updated to also look for the package file where we moved the links definition.

[TinaHeiligers]

What do you think about the package also allowing devs to register new doc links? We have a few different types ATM and would need to account for that and probably have different methods to generate the link fairly easily.

For example,
Kibana-related docs: ${ELASTIC_WEBSITE_URL}guide/en/kibana/${DOC_LINK_VERSION}/dashboard.html
Solutions docs: ${ELASTIC_WEBSITE_URL}guide/en/app-search/${DOC_LINK_VERSION} and ${ELASTIC_WEBSITE_URL}guide/en/security/${DOC_LINK_VERSION}/index.html etc.

The DocLinksService gets the current version from injectedMetadata (const DOC_LINK_VERSION = injectedMetadata.getKibanaBranch()), consumes ELASTIC_WEBSITE_URL (a static string) and then uses those to generate further links.

Is this a crazy idea?

[pgayvallet]

What do you think about the package also allowing devs to register new doc links?

The problem is that the doc build script is basically just regexp-parsing the content of the docLink file to extract the links, interpolate them against the variables, and then check the validity of the URLs (it's as scary as it sounds but that how that works currently), which is why we can't really use any kind of dynamic registration for links at the moment, as it will cause the doc CI job to just miss/ignore these links

As the CI job is meant to be 'very generic', as it gather and validate links from all products of the stack, I don't think this could be improved specifically for Kibana without a lot of work.

cc @gtback

[gtback]

Thanks for the ping @pgayvallet.

Yes, the current implementation doesn't evaluate any TypeScript code at all, it just munges the contents of the TypeScript file with Perl to pull out links and do some basic substitution. I'm not tied to that implementation, though (if there were some service that spit out a list of links to check as part of CI, or some other way to build a list of docs pages that Kibana links to, I'd be happy to adapt the docs link-checking code).

[lcawl]

Hopefully this issue would also address the need for hard-coded links in server-side code like the Fleet integration UX (per discussion in #113666 (comment))

[pgayvallet]

That would also allow deprecations registered on the server to use the docLink service instead of hardcoding documentation urls as it's done atm. See #112221 for more context

[pgayvallet]

So, we'll want to:

• Move the links definition from src/core/public/doc_links/doc_links_service.ts to a new @kbn/doc-links package
• Have the client-side DocLinksService uses this new module under the hood.
• Introduce a server-side version of this DocLinksService
• Change the doc build script to support this new location - https://github.com/elastic/docs/blob/b00435fdc5fb0342758280ffb30165226a5ec041/build_docs.pl#L414-L437

Also, the core team will NOT take ownership of the @kbn/doc-links package , to avoid unnecessary reviews when teams are adding links.

[gtback]

Thanks, @pgayvallet . One issue we've run into before is if there's a "stub file" in one of the old locations, it won't check the links in the newer location, unless we add new paths to the top of the if/else chain in build_docs.pl. Let me know if I can help with any of those changes.

[pgayvallet]

it won't check the links in the newer location, unless we add new paths to the top of the if/else chain in build_docs.pl

Yea, that was what I was planning to try. I'll make sure to ping you if I need anything, thank you