feat(v2): frontmatter-less: read first heading as title and use it in front-matter #4485

armano2 · 2021-03-21T14:51:24Z

Motivation

frontmatter always win
if no frontmatter and an h1 heading is at the very top, we use it as title instead of the filename
if no frontmatter and an h1 heading is found in the middle of a doc, we ignore it
#4425 (comment)

if front-matter title is present 
  use front-matter title
else if try reading header
  use header as front-matter title and conditionally remove it from content
else 
  old behavior

if front-matter title and header is present
  use front-matter title and print warning

typescript-eslint/typescript-eslint#3147
fixes #4425

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

~~i'm unsure where to put unit tests for this as i can't find any other unit tests for utils~~

/api/CLI should correctly read heading and use it as title
any other doc should read title field correctly
blog post should correctly print headings when # or title field is used
/examples/markdownPageExample should print heading for markdown page

content can/should be modified by hand to see if data is printed correctly.

netlify · 2021-03-21T14:54:35Z

[V1] Deploy preview failure

Built without sensitive environment variables with commit c4c002b

https://app.netlify.com/sites/docusaurus-1/deploys/6059031c94ccce0008ea2e52

netlify · 2021-03-21T14:59:51Z

Deploy preview for docusaurus-2 ready!

Built without sensitive environment variables with commit c4c002b

https://deploy-preview-4485--docusaurus-2.netlify.app

github-actions · 2021-03-21T15:00:02Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	87
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4485--docusaurus-2.netlify.app/

packages/docusaurus-utils/src/index.ts

idontknowjs · 2021-03-22T07:20:53Z

hey @armano2 , I'm a Docusaurus user. This feature sounds cool, will surely align to my usecase
By default when title is present in front-matter, it is also passed to sidebar_label and the name of the sidebar label gets changed to title.

In your case, will it happen too that the sidebar_label will also change as per the first heading along with the title?

armano2 · 2021-03-22T07:26:21Z

yes, that's a default behavior, if no sidebar label is present title is used instead, in /api/CLI you can actually see that happening

armano2 · 2021-03-22T10:31:42Z

tests added to blog and docs

armano2 · 2021-03-22T17:52:28Z

website/docs/cli.md

 ---

+# CLI


i can rollback this md file change as proper tests are now added

Suggested change

---

# CLI

title: CLI

---

Oh I think it's fine and we should dogfood this a bit too ;)

slorber · 2021-03-22T18:57:04Z

That looks nice, thanks for working on this! Will review this more deeply tomorrow.

Was wondering, do you think we should handle pages like docs and blog posts and automatically add the h1 tag to templates? It looks like we have a non-uniform setup that complicates a bit the code as pages should not remove the markdown heading.

I'd also like to have more tests for readFrontMatter and its edge cases, do you want to write some or can I edit your PR?

slorber · 2021-03-22T18:58:39Z

packages/docusaurus-utils/src/index.ts

+    const heading = /^# (.*)[\n\r]?/gi.exec(result.content);
+    if (heading) {
+      if (result.data.title) {
+        console.warn(
+          `Duplicate title detected in \`${source || 'this'}\` file`,
+        );
+      } else {
+        result.data.title = heading[1].trim();
+        if (removeTitleHeading) {
+          result.content = result.content.replace(heading[0], '');
+          if (result.excerpt) {
+            result.excerpt = result.excerpt.replace(heading[1], '');
+          }


wonder if we could extract this easily in a separate function and test this in isolation?

we could actually go few steps further in separate pr

index should jsut be an entry point with bunch of reexports and we could create multiple files with specific things.
this file is starting to become really long and unreadable

totally agree :)

was like that before and want to refactor that for a long time already

armano2 · 2021-03-22T20:19:56Z

Was wondering, do you think we should handle pages like docs and blog posts and automatically add the h1 tag to templates? It looks like we have a non-uniform setup that complicates a bit the code as pages should not remove the markdown heading.

this could be done but not in this PR, as we should not include to much changes at once

I'd also like to have more tests for readFrontMatter and its edge cases, do you want to write some or can I edit your PR?

~~i will try to add some tests, I'm not really familiar with convention in this project yet, as each project likes to do tests in different way~~
i added more test cases

circleci is failing after merge with master, same issue is preset on master

slorber · 2021-03-23T16:47:09Z

Thanks

circleci is failing after merge with master, same issue is preset on master

yes we just removed CircleCI, will be fine now :)

slorber

Thanks! that looks great

slorber · 2021-03-23T17:04:38Z

packages/docusaurus-utils/src/index.ts

+    const heading = /^# (.*)[\n\r]?/gi.exec(result.content);
+    if (heading) {
+      if (result.data.title) {
+        console.warn(
+          `Duplicate title detected in \`${source || 'this'}\` file`,
+        );
+      } else {
+        result.data.title = heading[1].trim();
+        if (removeTitleHeading) {
+          result.content = result.content.replace(heading[0], '');
+          if (result.excerpt) {
+            result.excerpt = result.excerpt.replace(heading[1], '');
+          }


totally agree :)

was like that before and want to refactor that for a long time already

armano2 · 2021-03-23T18:54:39Z

i just realized that this behavior is undocumented, maybe we should add it to docs?

slorber · 2021-03-23T19:06:48Z

oh yes that could be nice thanks :)

We have a good place for that: https://docusaurus.io/docs/next/markdown-features/headings

slorber · 2021-04-09T14:40:32Z

FYI I don't think it's a good idea to put the content title in the frontmatter object, it's a bit confusing because indeed it's not frontmatter.

Just wanted to let you know in case you depend on frontMatter.title being available despite not being set by real frontmatter.

Will revert this in #4590

Sotty75 · 2021-04-22T07:31:32Z

I have reported a bug on how titles are handled after updating to latest stable version.
This worked as a breaking change for me, also now all level 2 headers placed at the top of the document are rendered as standard text, not properly formatted. #4665

I added an example of how this is broken, check the following link, intro.md

https://codesandbox.io/s/vigorous-wood-d2cz7?file=/docs/intro.md

slorber · 2021-04-22T16:04:27Z

I believe it is a bug fix, not a breaking change, as we should not have allowed you to write a h1 title in frontmatter + markdown, and it is something to avoid

We didn't expect this would be annoying for anyone because it is a weird thing to do in the first place (or I'd like to know your motivations)

feat(v2): read first heading as title and pass it to front-matter

7876f15

armano2 requested review from lex111 and slorber as code owners March 21, 2021 14:51

facebook-github-bot added the CLA Signed Signed Facebook CLA label Mar 21, 2021

armano2 commented Mar 21, 2021

View reviewed changes

packages/docusaurus-utils/src/index.ts Outdated Show resolved Hide resolved

armano2 added 3 commits March 21, 2021 16:30

fix(v2): always trim content after extracting front-matter

8eb6ff5

fix(v2): remove heading from rss and keep duplicate heading

b3b5dca

fix(v2): rollback some unnecessary comment changes

e4c8a14

armano2 changed the title ~~feat(v2): read first heading as title and pass it to front-matter~~ feat(v2): read first heading as title and pass it as front-matter Mar 22, 2021

test(v2): add unit tests to blog

c199856

test(v2): add unit tests to docs

be80201

armano2 force-pushed the feat/frontmatter-title branch from e3f6cd5 to be80201 Compare March 22, 2021 10:34

test(v2): correct issue on windows

b57cdd2

armano2 commented Mar 22, 2021

View reviewed changes

armano2 changed the title ~~feat(v2): read first heading as title and pass it as front-matter~~ feat(v2): read first heading as title and use it as front-matter Mar 22, 2021

armano2 changed the title ~~feat(v2): read first heading as title and use it as front-matter~~ feat(v2): read first heading as title and use it as front-matter title Mar 22, 2021

armano2 changed the title ~~feat(v2): read first heading as title and use it as front-matter title~~ feat(v2): read first heading as title and use it as front-matter Mar 22, 2021

armano2 changed the title ~~feat(v2): read first heading as title and use it as front-matter~~ feat(v2): read first heading as title and use it in front-matter Mar 22, 2021

idontknowjs mentioned this pull request Mar 22, 2021

Allow configuring the title of a sidebar link in sidebar.js in plugin-docs #4314

Closed

slorber reviewed Mar 22, 2021

View reviewed changes

armano2 added 2 commits March 22, 2021 21:23

Merge branch 'master' into feat/frontmatter-title

b660081

test(v2): add additional test cases

c4c002b

slorber approved these changes Mar 23, 2021

View reviewed changes

slorber merged commit ea13c94 into facebook:master Mar 23, 2021

armano2 deleted the feat/frontmatter-title branch March 23, 2021 17:08

slorber mentioned this pull request Mar 23, 2021

Auto generate sidebar according to the docs folder structure #3464

Closed

felipecrs mentioned this pull request Mar 23, 2021

docusaurus: inject 'slug: /' in api/index.md typedoc2md/typedoc-plugin-markdown#143

Closed

armano2 mentioned this pull request Mar 24, 2021

fix(v2): do not warn about duplicated title for pages #4507

Merged

slorber mentioned this pull request Apr 9, 2021

feat(v2): various markdown string parsing improvements/fixes #4590

Merged

slorber changed the title ~~feat(v2): read first heading as title and use it in front-matter~~ feat(v2): frontmatter-less: read first heading as title and use it in front-matter Apr 16, 2021

slorber added the pr: new feature This PR adds a new API or behavior. label Apr 16, 2021

slorber mentioned this pull request Jun 2, 2021

fix(v2): fix contentTitle issues when markdown h1 title contains code blocks #4882

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): frontmatter-less: read first heading as title and use it in front-matter #4485

feat(v2): frontmatter-less: read first heading as title and use it in front-matter #4485

armano2 commented Mar 21, 2021 •

edited

netlify bot commented Mar 21, 2021 •

edited

netlify bot commented Mar 21, 2021 •

edited

github-actions bot commented Mar 21, 2021 •

edited

idontknowjs commented Mar 22, 2021

armano2 commented Mar 22, 2021 •

edited

armano2 commented Mar 22, 2021

armano2 Mar 22, 2021

slorber Mar 22, 2021

slorber commented Mar 22, 2021

slorber Mar 22, 2021

armano2 Mar 22, 2021 •

edited

slorber Mar 23, 2021

armano2 commented Mar 22, 2021 •

edited

slorber commented Mar 23, 2021

slorber left a comment

slorber Mar 23, 2021

armano2 commented Mar 23, 2021

slorber commented Mar 23, 2021

slorber commented Apr 9, 2021

Sotty75 commented Apr 22, 2021 •

edited

slorber commented Apr 22, 2021 •

edited

----
-# CLI
+title: CLI
+---

feat(v2): frontmatter-less: read first heading as title and use it in front-matter #4485

feat(v2): frontmatter-less: read first heading as title and use it in front-matter #4485

Conversation

armano2 commented Mar 21, 2021 • edited

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

netlify bot commented Mar 21, 2021 • edited

netlify bot commented Mar 21, 2021 • edited

github-actions bot commented Mar 21, 2021 • edited

idontknowjs commented Mar 22, 2021

armano2 commented Mar 22, 2021 • edited

armano2 commented Mar 22, 2021

armano2 Mar 22, 2021

Choose a reason for hiding this comment

slorber Mar 22, 2021

Choose a reason for hiding this comment

slorber commented Mar 22, 2021

slorber Mar 22, 2021

Choose a reason for hiding this comment

armano2 Mar 22, 2021 • edited

Choose a reason for hiding this comment

slorber Mar 23, 2021

Choose a reason for hiding this comment

armano2 commented Mar 22, 2021 • edited

slorber commented Mar 23, 2021

slorber left a comment

Choose a reason for hiding this comment

slorber Mar 23, 2021

Choose a reason for hiding this comment

armano2 commented Mar 23, 2021

slorber commented Mar 23, 2021

slorber commented Apr 9, 2021

Sotty75 commented Apr 22, 2021 • edited

slorber commented Apr 22, 2021 • edited

armano2 commented Mar 21, 2021 •

edited

netlify bot commented Mar 21, 2021 •

edited

netlify bot commented Mar 21, 2021 •

edited

github-actions bot commented Mar 21, 2021 •

edited

armano2 commented Mar 22, 2021 •

edited

armano2 Mar 22, 2021 •

edited

armano2 commented Mar 22, 2021 •

edited

Sotty75 commented Apr 22, 2021 •

edited

slorber commented Apr 22, 2021 •

edited