feat: adds blog archive route

[gabrielcsapo]

Motivation

Fixes #4431

Special thanks to @johnnyreilly (https://blog.johnnyreilly.com/2021/05/01/blog-archive-for-docusaurus) for the inspiration and starting an issue to have this added.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Navigating to http://localhost:3000/blog/archive when serving the website via (cd website;yarn start;) will yield the new blog archive page. Please see the attached screenshot the expected output.

Related PRs

Docs have been updated in this PR to reflect the new option.

[facebook-github-bot]

Hi @gabrielcsapo!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	75
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

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

[netlify]

✔️ [V2]

🔨 Explore the source changes: 298b20b

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/6130ea99ebb7830008c0ae71

😎 Browse the preview: https://deploy-preview-5428--docusaurus-2.netlify.app

[gabrielcsapo]

CLA signed

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[gabrielcsapo]

cc @slorber

[slorber]

Thanks @gabrielcsapo

I cleaned up a bit your PR and added missing i18n support.

Going to merge/release it now in beta.6

We can still improve this page in the future but at least an initial version is here.
We could link to it in the sidebar once it's ready to become more "visible" and we consider the design stable enough.

[lex111]

I think it's better to use reverse chronological order, and maybe just content as lists, including date of posts? Like on Bootstrap blog:

[slorber]

I think it's better to use reverse chronological order, and maybe just content as lists, including date of posts?

Oh sorry just saw your comment after merging 😅 wanted to merge it fast because I'm releasing beta.6 asap and it seemed good enough for a first version.

Yes I actually found the years ordering a bit weird, and the design can be improved, please feel free to do so in another PR for the next release

[lex111]

Don't worry, I'll try to find more examples of blog archives, and then probably improve current design.

[johnnyreilly]

I think it's better to use reverse chronological order, and maybe just content as lists, including date of posts?

Agree with this. I'm so pleased this landed; I think it needs a little polish though. This is what it looks like on my own blog:

The "Archive... Archive" could be tweaked to make more lovely I think

I read the PR a little closer and this can be configured with the docusaurus.config.js blog section:

archive.description
archive.title

[johnnyreilly]

I just tried to use the archive.description / archive.title functionality and was presented with this:

A validation error occurred.
The validation system was added recently to Docusaurus as an attempt to avoid user configuration errors.
We may have made some mistakes.
If you think your configuration is valid and should keep working, please open a bug report.

This is my section of docusaurus.config.js:

  presets: [
    [
      '@docusaurus/preset-classic',
      ({
        docs: false,
        blog: {
          archive: {
            title: 'Blog Archive',
            description: 'Historic posts'
          },
          blogTitle: 'I CAN MAKE THIS WORK',
          blogDescription: 'The blog of johnnyreilly',
          /**
           * Number of blog post elements to show in the blog sidebar
           * 'ALL' to show all blog posts
           * 0 to disable
           */
          blogSidebarCount: 5,
          postsPerPage: 1,
          path: "./blog",
          routeBasePath: "/", // Set this value to '/'.
          showReadingTime: true,
          editUrl:
            "https://github.com/johnnyreilly/blog.johnnyreilly.com/edit/main/blog-website/blog/",
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],

It's possible I'm doing it wrong; but I am unable to work out how to do it right.... Moving the archive section up a level doesn't seem to work either.

As well as the console error it doesn't seem to affect the content of the generated page either?

I'm not sure if this is a bug or user error...

[Josh-Cena]

Can it be configured though? The theme.blog.archive.description is only an ID for translation and doesn't have any implications of configuration structure. The only config option right now is archiveBasePath

[johnnyreilly]

Maybe it can't be configured. If it can't it's probably something that would be desirable

[Josh-Cena]

Definitely worth improving on. Also, if we add this in options, we will transfer the translation to plugin-blog instead, and we can start to populate the options.json file😉

[slorber]

You can use the i18n support tu customize all English labels, I don't think it's worth it to add an option for each individual label Le sam. 4 sept. 2021 à 15:18, Joshua Chen ***@***.***> a écrit :

…

Definitely worth improving on. Also, if we add this in options, we will transfer the translation to plugin-blog instead, and we can start to populate the options.json file😉 — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#5428 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFW6PWY2XLZFF2LUWDWKGTUAITCXANCNFSM5C3YWNXQ> .

[Josh-Cena]

You can use the i18n support tu customize all English labels, I don't think it's worth it to add an option for each individual label

In the same way we allow customizing the sidebar title and the blog title, we should allow customizing the archive title. For example, my site has a default en locale and a translated zh-Hans locale under i18n, and I never write any en translation because that's supposed to be the "default". Using i18n to customize labels means I essentially have to start a new locale under the i18n folder. If that's the encouraged practice in the future, we can actually get rid of a lot of text label options in the config file, but is that desirable on the user side? At least not for the people not using i18n IMO

[slorber]

We have a lot of text, aria labels etc in multiple places the theme and plugins.

Adding all those to options would be quite overwhelming and create a large option api surface that would have breaking changes when we refactor UI.

I feel it's more convenient and future proof to document better that the way to customize default english labels is by using docusaurus write-translations and customizing the labels in i18n/en/code.json

At the same time the other files would feel "duplicate" (user does not want to translate the sidebar because it's already localized correctly). We should probably provide a way to override theme labels without using the i18n/en folder, probably thanks to an extra Docusaurus config.