Docs-only mode doesn't work

[tlm28]

Docs-only mode doesn't work

I ran the following command to install Docusaurus 2.0.0-alpha.65:

$ npx @docusaurus/init@next init website classic

and follow the instructions in
https://v2.docusaurus.io/docs/docs-introduction/#docs-only-mode
to get rid of the landing page:

1. Add "routeBasePath: '/'" (under presets) to docusaurus.config.js.
2. Delete the file src/pages/index.js.

When I built the site, I get these error messages:

Error: Broken links found!

• Page path = /404.html:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/hello-world:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/hola:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags/docusaurus:
  -> link to /docs/
  -> link to /docs/doc2/
  ...

Is this a bug in Docusaurus 2.0.0-alpha.65?

[slorber]

Hi,

The "docs-only" name may be misleading, but using routeBasePath: '/' does only set the / URL for docs, but it does not disable the blog.

If you want to disable the blog, pass blog: false to the classic preset

If you want to keep the blog, the remaining blog posts should not link anymore to /docs/ because your docs are at / now, so this is not a bug, it's a feature that prevented you from deploying a blog as you may not actually need it, and if you need it, you would have broken links.

Reading the whole error message you'll also notice that there is an option to disable/ignore this log and let the build pass, in case yu can't fix the broken links right now but want to deploy the site with broken links.

[tlm28]

I want to get rid of the landing page and keep the blog. I follow the instructions in https://v2.docusaurus.io/docs/docs-introduction/#docs-only-mode to do that, but clearly they don't work.

[tlm28]

Why should I deploy a site with broken links?

[JoelMarcey]

Why should I deploy a site with broken links?

@tlm28 I don't think @slorber is suggesting you deploy a site with broken links. He is saying you can workaround it short-term, build/load the site and ignore the errors while you work out the issue re: whether you want a blog or not. In other words, I believe he is first asking whether you want to disable the blog or not. And if you don't, you need to set blog: false. And if you do that, the errors should go away.

[tlm28]

We do want to keep the blog.

The broken links include paths to docs. Here's the complete list of the errors:

Error: Broken links found!

• Page path = /404.html:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/hello-world:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/hola:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags/docusaurus:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags/facebook:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags/hello:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/tags/hola:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /blog/welcome:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /doc2:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /doc3:
  -> link to /docs/
  -> link to /docs/doc2/

• Page path = /mdx:
  -> link to /docs/
  -> link to /docs/doc2/

[slorber]

@tlm28 I'm sorry, as your error message was incomplete (only showing first errors, related to blog pages), I thought it was related to the blog, but it is probably related to your layout / theme configuration instead, and affect all the pages (not only blog).

If you used the Facebook template, you should have this default footer config:

You have in practice 2 links to /docs/ and /docs/doc2 from your footer, appearing on all the pages of your site, and those links do not exist anymore because you decided to move /docs/ to /, and /docs/doc2 to /doc2.

The current system is just a failfast way to prevent you from deploying a footer with broken links in production, and ensure you fix those links first, by using footer config such as:

{
          items: [
            {
              label: 'Style Guide',
              to: '/',
            },
            {
              label: 'Second Doc',
              to: '/doc2',
            },
          ],
        },

---

Also, as it's displayed at the very end in the error message (made this message more visible in PR #3569), there an onBrokenLinks setting to disable this behavior, if you really want to not block a deployment when we detect broken links. https://v2.docusaurus.io/docs/docusaurus.config.js/#onbrokenlinks

I do not recommend using this unless you have good reasons, as this broken links detection feature actually prevented you from deploying a broken footer that you actually didn't notice.

---

This feature works as intended. I do agree that it may be confusing to have such a verbose error output, but in practice, this is because a broken link is found in ALL pages of your site, due to being part of the site layout. Will try to improve the error message a bit regarding this.

[slorber]

The new error message will be:

Let me know if you think it's not clear enough to understand what's going on.

[tlm28]

Thanks @slorber.

[plocket]

I just ran into this issue and did not find the errors clear because I assumed that the instructions at https://v2.docusaurus.io/docs/docs-introduction/#docs-only-mode would include everything we'd need to do to change to only having docs.

Maybe the documentation for docs-only-mode needs to be improved. For example, adding instructions about where we'd need to edit references to /docs/ might help. If not that, then at least an explanation of the errors that will pop up.

Not sure if it's possible, but another alternative would be for the docs plugin to try to account for /docs/ references, making sure they get treated as / instead. That could cause issues down the line, though.

Edit: For future people using classic, this is what worked for me:
Go to your docusaurus.config.js. Find themeConfig.navbar.items. Remove the item there that has activeBasePath: 'docs':

      items: [
       // Remove this item
        {
          to: 'docs/',
          activeBasePath: 'docs',
          label: 'Docs',
          position: 'left',
        },
        {
          href: 'https://github.com/user_name/repo_name',
          label: 'GitHub',
          position: 'right',
        },
      ],

[slorber]

@plocket any doc PR is welcome if you feel you can improve the instructions

[adelavega]

Just wanted to say I had a similar issue, agree updating the docs to mention the footer has to be modified -- if using the template -- would be helpful