feat(core): postStart plugin lifecycle

[gabrielcsapo]

trafficstars

Pre-flight checklist

• [x] I have read the Contributing Guidelines on pull requests.
• [x] If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• [x] If this is a new API or substantial change: the PR has an accompanying issue (closes #7749) and the maintainers have approved on my working plan.

Motivation

Closes #7749 and implement postStart hook to compliment postBuild hook.

Test Plan

I have a plugin locally that I linked against this version and the hook performs as expected.

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

[netlify[bot]]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	7e085d93d9fd1941d5b8b835e88af5ef914ed400
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/62ccd539dc8fe90009d529b3
😎 Deploy Preview	https://deploy-preview-7751--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions[bot]]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 80	🟢 100	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 85	🟢 100	🟢 100	🟢 100	🟢 90	Report

[gabrielcsapo]

I can add a test, does it make sense to move the open browser code to the default plugin and have that implement postStart and test the browser was opened correctly by proxy? @Josh-Cena

[gabrielcsapo]

my mind has played tricks on me, there is no default plugin that we could move it to.

[Josh-Cena]

does it make sense to move the open browser code to the default plugin

I thought about that haha, but we don't pass CLI options to plugins, so I think it makes more sense to make it stay in the core.

Also, there's no "default plugin", but there's the idea of "synthesized" plugin, in src/server/plugins/synthetic.ts

[gabrielcsapo]

Makes sense!

I can write a test in the synthesized plugin that basically just makes sure the hook gets called on start. Does that work?

[Josh-Cena]

We don't have these kinds of tests for now—that's not an immediate goal, so I think this PR is good enough as-is.

[gabrielcsapo]

Alright, no worries. I can add tests whenever a strategy is defined.

Really appreciate the help and dialogue @Josh-Cena!

[gabrielcsapo]

@Josh-Cena do you know who has to approve to merge?

[Josh-Cena]

Oh, all public API additions will be reviewed by @slorber. He works from Wednesday to Friday.

[gabrielcsapo]

Thank you @Josh-Cena, sorry for the ping!

[gabrielcsapo]

@slorber did you happen to get a chance to look at this?

[slorber]

@gabrielcsapo as we released RC.1 I'm focusing on 2.0 and postponing any task related to additional features. I will take a look but unfortunately not now

[gabrielcsapo]

@slorber would this be something that could make it into a minor release?

[gabrielcsapo]

@slorber I will implement the potential experience using the webpack extension you brought up.

The search plugin is an iterative one that we have built on top of. I think you are right that we shouldn't be crawling the html with cheerio and instead have something that is more integrated into the documentation experience rather than abstracted.

Ideally this information exists in memory in a specific format that docusaurus utilizes for its plugin system and I will look at utilizing that data source as a way to build the search index instead.

It is great to hear that you are all thinking of building a local search feature and look forward to that! We have over 50+ documentation sites using docusaurus that are using search internally and would really like to collaborate if you are willing!

[slorber]

Thanks @gabrielcsapo

Really curious to see how you build this considering there's no HTML file written to the filesystem in dev.

Definitively looking to working with you on this to define the API for Docusaurus to enable the creation of good local search plugins + create a core one.

I have more important tasks to handle ATM but we definitively want to have an official core plugin for local search.

By the way we already tried to work on this (https://github.com/facebook/docusaurus/pull/3153) and also used the postBuild hook to scrape the HTML files.

Unfortunately as we are using MDX I'm not even sure there's another easy alternative to read HTML files. We'll figure this out, maybe we could have something in Docusaurus core that helps implement all this in a better way, less likely to break.

Note we have a helper used in the blog RSS feed you may find useful:

import { readOutputHTMLFile } from "@docusaurus/utils";

const content = await readOutputHTMLFile(
  permalink.replace(siteConfig.baseUrl, ""),
  outDir,
  siteConfig.trailingSlash
);
const $ = cheerioLoad(content);

const feedItem: FeedItem = {
  // ...
  content: $(`#${blogPostContainerID}`).html()!
};

It's not ideal but it works. And maybe we can use the sitemaps logic to know all the relevant routes to index (and thus all the HTML files)

[gabrielcsapo]

@slorber ideally we would want the build system to be the provider of the data. Given how flexible the surface area is we would want to make sure that all data rendered to a page can be searchable not just classic markdown.

I met with @lbdm44 who has been working on the plugin for search for our company and we came up with a few ways we might be able to improve the existing infra. Specifically as a feature request came in to show tags inline with search results if the page the search result is on has them.

The RSS feed is an interesting one, I am going to look into that this week and we can collaborate on it together. Does it make sense to make this a discussion and chat there?

[slorber]

We could move the discussion to this new entry I just created: https://github.com/facebook/docusaurus/discussions/8283

[slorber]

@gabrielcsapo considering postStart is IMHO unlikely to solve the local search DX problem, going to close this PR for now.

We can reopen if someone can come up with a good use-case for this hook, preferably with a configureWebpack userland implementation to present.

Let's pursue the discussion in https://github.com/facebook/docusaurus/discussions/8283