Tutorial feedback #4610

slorber · 2021-04-13T17:29:13Z

slorber
Apr 13, 2021
Collaborator

Docusaurus tutorial

The Docusaurus tutorial is very important: it is the very first thing a Docusaurus user sees (init template or CodeSandbox)

Please report here if anything does not work or is unclear.

mpoundstone · 2021-07-23T19:41:36Z

mpoundstone
Jul 23, 2021

To be honest, I've been having a lousy time trying to figure out to get http://localhost:3000 working on my Mac. How necessary is activating a local web server for this tutorial and for Docusaurus as a whole? If it's absolutely essential, can that step be added to the list of requirements alongside Node and Yarn?

5 replies

slorber Jul 23, 2021
Collaborator Author

You don't need a local web server at all, just nodejs > 12 + yarn/npm.
Running yarn build && yarn serve should be enough to have a production build running locally.
Docusaurus ships with an embedded very simple web server (yarn serve).

Can you explain what you struggle with?
Can you share error messages or whatever?
What specific parts of the tutorial are hard to understand?
Have you tried the online playgrounds?

mpoundstone Jul 23, 2021

You don't need a local web server at all, just nodejs > 12 + yarn/npm.

Ah, okay. Unfortunately, http://localhost:3000 still comes up as a blank webpage no matter which browser I use (Firefox, Chrome, Safari). It's loading something—here's the HTML I'm seeing:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="Docusaurus">
    <title>My Site</title>
    <link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="My Site Blog RSS Feed">
<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="My Site Blog Atom Feed">
    <script defer src="/runtime~main.js"></script><script defer src="/main.js"></script><link href="/styles.css" rel="stylesheet">
  </head>
  <body>
    <script>
(function() {
  var defaultMode = 'light';
  var respectPrefersColorScheme = false;

  function setDataThemeAttribute(theme) {
    document.documentElement.setAttribute('data-theme', theme);
  }

  function getStoredTheme() {
    var theme = null;
    try {
      theme = localStorage.getItem('theme');
    } catch (err) {}
    return theme;
  }

  var storedTheme = getStoredTheme();
  if (storedTheme !== null) {
    setDataThemeAttribute(storedTheme);
  } else {
    if (
      respectPrefersColorScheme &&
      window.matchMedia('(prefers-color-scheme: dark)').matches
    ) {
      setDataThemeAttribute('dark');
    } else if (
      respectPrefersColorScheme &&
      window.matchMedia('(prefers-color-scheme: light)').matches
    ) {
      setDataThemeAttribute('light');
    } else {
      setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
    }
  }
})();

            </script>
    <div id="__docusaurus"></div>
    
    
  </body>
</html>

I'm able to get the playgrounds to work, but my goal is to create a custom documentation site in GitHub pages that I'm able to edit from my local system.

In all fairness to the tutorial, it is extremely straightforward and every command generates exactly what it's supposed to. I'm also an absolute beginner to this level of technical work. I'm just not able to get a locally hosted Docusaurus file/folder to work on my browser and I'm not sure where I'm going wrong.

I'm going to try to go through the tutorial one more time, this time using my /Sites folder. I'll let you know what specific bugs/error messages come up, if any. Should I open a new issue for this (so I'm not cluttering up this discussion section)?

mpoundstone Jul 23, 2021

This time, it worked! Not a perfect test since I changed two conditions:

turning on my localhost using Apache
making the Docusaurus project in my Sites folder.

I can do further testing about which factor made the difference here, especially since, in theory, neither should not have affected the Docusaurus local web server at all.

mpoundstone Jul 26, 2021

Update: I'm absolutely a newbie and extremely embarrassed.

Turns out you have to keep the shell running the yarn start command open in order to have an active server. I was exiting the shell because it was like an off-on switch, and the fact that it wasn't returning to the command line made me think it was buggy.

My apologies. Thanks for replying so quickly.

slorber Jul 27, 2021
Collaborator Author

I see :D thanks for the explanations
Yes, you have to keep the shell open when in dev mode. Errors will be printed where as you edit your docs or site config.

collindang88 · 2021-07-23T23:50:49Z

collindang88
Jul 23, 2021

I just ran the command

npx @docusaurus/init@latest init my-website classic

to start my Docusaurus project and after running

yarn run start

two of the links on http://localhost:3000/docs/tutorial-basics/congratulations are already broken. I did not change the code at all. Is this a known problem? Pictures are attached and I am quite confused.

20 replies

slorber Aug 2, 2021
Collaborator Author

I can reproduce on MacOS too, will be fixed soon!

slorber Aug 2, 2021
Collaborator Author

this will be solved in #5270, thanks!

slorber Aug 2, 2021
Collaborator Author

please let me know if you have a bug with the canary release: https://docusaurus.io/community/canary

cainmagi Aug 2, 2021

@slorber
I have confirmed that the canary release does not have bugs. Here are my testing commands:

cd "C:\Documents (no sync)\Scripts"
conda activate docs
npx @docusaurus/init@canary init test-docusauraus-2 classic
cd test-docusauraus-2
yarn start

Thank you!

slorber Aug 4, 2021
Collaborator Author

great, thanks for the feedback ;)

juliannaroen · 2021-09-16T17:51:23Z

juliannaroen
Sep 16, 2021

The tutorial is amazing and quick! One thing I noticed is that when I tried the versioning portion of the tutorial, I saw this error message on the docs page after I ran npm run docusaurus docs:version 1.0:

Uncaught TypeError: Cannot destructure property 'description' of 'metadata' as it is undefined.

Here's a Loom which walks through the issue.

1 reply

slorber Sep 22, 2021
Collaborator Author

Thanks for the feedback @juliannaroen and thanks for creating a video

The tutorial says:

But you did:

This does not look the same to me 🤪 how can we make this clearer?

But I'm still surprised you get this runtime error though.

Have you tried restarting the docusaurus dev server after creating the version?
I'm not sure we support keep the dev server enabled while you run the versioning command in another terminal for example, maybe it's what you tried?

Chainguys · 2022-04-11T08:41:14Z

Chainguys
Apr 11, 2022

Final step "Build your site"

(base) paul@paulpauldeMacBook-Pro my-website % npm run build

my-website@0.0.0 build
docusaurus build

[INFO] [en] Creating an optimized production build...

✔ Client

✖ Server
Compiled with some errors in 21.03s

[ERROR] Docusaurus server-side rendering could not render static page with path /foo/bar/bar.

Error: Minified React error #130; visit https://reactjs.org/docs/error-decoder.html?invariant=130&args[]=object&args[]= for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
(base) paul@paulpauldeMacBook-Pro my-website %

3 replies

slorber Apr 13, 2022
Collaborator Author

@Chainguys please show us the content of your page /foo/bar/bar, it's likely you have an error in your code there. It does not seem related to our tutorial because we never ask you to create a page at /foo/bar/bar afaik

Josh-Cena Apr 13, 2022
Collaborator

@slorber Mentioned here: https://github.com/facebook/docusaurus/blob/main/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-page.md

With no prior knowledge in React or even coding in general, they assumed you just need to create an empty file with no content.

slorber Apr 13, 2022
Collaborator Author

ah ok 😅 so not sure how we can improve this 🤪 maybe move the routing rules/mapping/examples at the end? 🤷‍♂️

randomJoe211 · 2022-08-01T09:16:53Z

randomJoe211
Aug 1, 2022

The tutorial cannot be edited. If I click the Edit button, it reports 404.

7 replies

Josh-Cena Aug 1, 2022
Collaborator

Oh, that site is terribly outdated. cc @slorber We need to update it.

The best way to explore it is via CodeSandbox or setting it up locally.

randomJoe211 Aug 1, 2022

Oh, got it. Thanks for the heads-up.
I'm a newcomer. Not sure what CodeSandbox is, but I think I'll find out.
Setting it up locally feels cumbersome anyway.

Josh-Cena Aug 1, 2022
Collaborator

You can follow the guide here: https://docusaurus.io/docs/installation

randomJoe211 Aug 1, 2022

OK. Thank you!

slorber Aug 8, 2022
Collaborator Author

Ah thanks :D didn't notice but the Netlify deployment is failing

https://app.netlify.com/sites/docusaurus-tutorial

5:20:57 PM: error docusaurus@0.0.0: The engine "node" is incompatible with this module. Expected version ">=16.14". Got "12.18.0"

It's fixed now

chabroA · 2022-09-01T09:06:41Z

chabroA
Sep 1, 2022

Hello, great tutorial 🙌

Little feedback on the configure-the-sidebar part of the basic tutorial.

When editing the sidebars.js file as stated in the doc, I don't have a sidebar anymore on my website.

Editing the tutorialSidebar object:

Or even copy / pasting the exact code from the doc (everything else from the original file is commented out)

No sidebar anymore.

I would assume I am supposed to see a sidebar.
It would be great also to add some information about what we are supposed to see / what is supposed to happen when we update this sidebars.js to create it explicitly.

2 replies

slorber Sep 1, 2022
Collaborator Author

Thanks for the feedback, I see how it can be confusing

The sidebar is only displayed on docs it contains:

the sidebar is displayed on the "hello" doc
the sidebar isn't displayed on the "create-a-document" doc because it doesn't contain that doc

I'll update the tutorial to make sure following these instructions from the current page would still display the sidebar. Solution:

  tutorialSidebar: [
    {
      type: 'category',
      label: 'Tutorial',
      items: ['create-a-document', 'hello'],
    },
  ],

Will be handled in #8032

chabroA Sep 5, 2022

Ok I see how this works now, thanks for the answer

slorber · 2022-09-01T10:50:32Z

slorber
Sep 1, 2022
Collaborator Author

No mention of site config / themeConfig

Our tutorial doesn't currently show some basic things such as explaining the site config file, and in particular themeConfig

I guess we should add a step at the end of the basic tutorial to at least show the user how to add navbar/footer items?

As a temporary workaround, I mentioned those in #8032

0 replies

luishernandezv · 2022-10-30T07:11:08Z

luishernandezv
Oct 30, 2022

Hi there nice tutorial!

I'm looking into the Markdown Features Section, specifically at the Images. Here I see this You can reference images relative....

It seems that link at the end is taking users to the wrong place

Even if you go to the tutorial extras site you'll see this

Am I missing something about where that part of the tutorial is?

Thanks!

1 reply

slorber Nov 2, 2022
Collaborator Author

Thanks. There's actually an example on the target page (source code) but I can see how it is confusing. Fixed in #8279

ianp-its · 2024-01-03T16:40:46Z

ianp-its
Jan 3, 2024

Hi. I can't find out anything in the tutorial about changing the sample code languages (currently it defaults to cURL, Go, Node and Python). Assuming it is possible for a mere mortal to change this via configuration, could this please be included in the documentation?
Thanks!

2 replies

slorber Jan 4, 2024
Collaborator Author

@ianp-its I don't understand what you mean

currently it defaults to cURL, Go, Node and Python

??? please explain what you mean by that

could this please be included in the documentation?

This issue is for the tutorial, and it is kept short on purpose. Maybe it would be better to document what's missing in the official doc site instead?

ianp-its Jan 4, 2024

No worries. My mistake.

heysokam · 2024-01-03T17:28:40Z

heysokam
Jan 3, 2024

Found a bug in one of the pages markdown examples
#9694

Edit: will be fixed in #9696

0 replies

Oobiewan · 2024-08-27T16:46:14Z

Oobiewan
Aug 27, 2024

I'm not sure if I'm the right target audience as I don't know javascript (is it mentioned anywhere that knowing javascript is a prerequisite?), but I got a bit stuck at the translation part (https://github.com/facebook/docusaurus/blob/main/packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.md).
The tutorial instructs me to modify docusaurus.config.js to add support for the fr locale:

export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
};

But in the used "my-website" project, the config file only has an i18n object within "const config". So it's not clear what I am supposed to do with this snippet, append it to the end of the file? Replace the "export default" part at the end of the file?
Copilot tells me I should simply edit the existing i18n part under "const config", which seems to make sense, but it won't match the snippet in the tutorial.

1 reply

slorber Aug 27, 2024
Collaborator Author

Yes you can modify the i18n attribute directly, using export default {} or export default config leads to the same for JS: the config object you write gets exported.

This comment has been hidden.

Sign in to view

This comment has been hidden.

Sign in to view

This comment has been hidden.

Sign in to view

Tutorial feedback #4610

slorber Apr 13, 2021 Collaborator

Docusaurus tutorial

Replies: 12 comments · 43 replies

slorber Jul 23, 2021 Collaborator Author

slorber Jul 27, 2021 Collaborator Author

slorber Aug 2, 2021 Collaborator Author

slorber Aug 2, 2021 Collaborator Author

slorber Aug 2, 2021 Collaborator Author

slorber Aug 4, 2021 Collaborator Author

This comment has been hidden.

This comment has been hidden.

slorber Sep 22, 2021 Collaborator Author

slorber Apr 13, 2022 Collaborator Author

Josh-Cena Apr 13, 2022 Collaborator

slorber Apr 13, 2022 Collaborator Author

Josh-Cena Aug 1, 2022 Collaborator

Josh-Cena Aug 1, 2022 Collaborator

slorber Aug 8, 2022 Collaborator Author

slorber Sep 1, 2022 Collaborator Author

slorber Sep 1, 2022 Collaborator Author

No mention of site config / themeConfig

slorber Nov 2, 2022 Collaborator Author

slorber Jan 4, 2024 Collaborator Author

slorber Aug 27, 2024 Collaborator Author

slorber
Apr 13, 2021
Collaborator

Replies: 12 comments 43 replies

slorber Jul 23, 2021
Collaborator Author

slorber Jul 27, 2021
Collaborator Author

slorber Aug 2, 2021
Collaborator Author

slorber Aug 2, 2021
Collaborator Author

slorber Aug 2, 2021
Collaborator Author

slorber Aug 4, 2021
Collaborator Author

slorber Sep 22, 2021
Collaborator Author

slorber Apr 13, 2022
Collaborator Author

Josh-Cena Apr 13, 2022
Collaborator

slorber Apr 13, 2022
Collaborator Author

Josh-Cena Aug 1, 2022
Collaborator

Josh-Cena Aug 1, 2022
Collaborator

slorber Aug 8, 2022
Collaborator Author

slorber Sep 1, 2022
Collaborator Author

slorber
Sep 1, 2022
Collaborator Author

slorber Nov 2, 2022
Collaborator Author

slorber Jan 4, 2024
Collaborator Author

slorber Aug 27, 2024
Collaborator Author