DocFrontMatterSchema export

[trevor-moore-dev]

Wondering if the DocFrontMatterSchema in the plugin-content-docs package could be exposed? Same would go for the schemas for pages, blogs, etc. Reason being is we'd like to validate front matter prior to running a docusaurus build. Otherwise I'll just construct the schema myself using the exports from utils-validation (would rather not since the schema could change on docusaurus' end).

[slorber]

In general we try to not expose too much as public API because it prevents us from doing breaking changes.

However we are quite permissive in how we currently use exports, so technically you can import almost anything:

"exports": {
    "./lib/*": "./lib/*",
    "./src/*": "./src/*",
  },

Note that I'm very likely to remove those for v4.

Be aware that importing internals can break at any time. We may even switch to Zod for example, and since it's not public API, we can do this in a minor version.

utils-validation is also considered internals

If you want us to publicly expose something and maintain semver retrocompatibility, we really need to understand better your motivations and design an explicit public API for the feature

[trevor-moore-dev]

Thanks for such a prompt response @slorber. I had discovered the exports and got it working after I asked the question, hence the closure.

But thanks for bringing that up, since my team and I would really appreciate to have this functionality exposed for our use case. I'll elaborate...

Basically, we pull docs from a growing list of repositories. As this list grows, so does the build time. Before a repository's docs get added to the project, we want to ensure that it won't break the build (we run continuous deployments due to the static nature of SSG and content that may change from commits to the repos). Previously, we would run a "test" docusaurus build with the new repo along with all the others, but this took a long time and contributes to a poor UX (we allow users to add repository docs via interface). In an effort to expedite this process, I found "parseMarkdownFile" in @docusaurus/utils and "validateFrontMatter" in @docusaurus/utils-validation, which we now use to validate the repo prior to adding it to the project. This process is much faster than running an entire docusaurus build and in (our) theory performs the same checks that docusaurus does under the hood.

In short, we'd like to be able to ensure that docs won't break our build, prior to including them in our build.

[slorber]

How can you be sure that docs won't break your build by just validating front matter? That's only one part of the problem, your docs might also use components, directives, JSX or whatever that your Docusaurus version doesn't like.

If you want to validate that the source repo has valid MDX syntax (including syntax extensions that your Docusaurus site might support, such as GFM, directives, Remark-math, MDX HTML comments...) you have to run the full MDX compiler with the exact same plugins too, and it's not even covering that the MDX doc will be able to render properly, only catch the most common errors.

Note if you only want to validate docs structure, front matter and consistency, we have a secret env variable that we use in CI: E2E_TEST=true docusaurus start will not bundle/ssg your app and just stop at loading data, verifying it's consistent with what we expect (including front matter). That part is usually much faster than a full build since bundling / ssg is the most expensive part.

[trevor-moore-dev]

We simply want to catch the most common errors, not necessarily perform a catch all, since most often we run into front matter issues. Thanks for the suggestion on the env variable, I'll definitely take a look into that.