Replies: 15 comments 46 replies
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
You don't need a local web server at all, just nodejs > 12 + yarn/npm. Can you explain what you struggle with? |
Beta Was this translation helpful? Give feedback.
-
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: 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)? |
Beta Was this translation helpful? Give feedback.
-
|
This time, it worked! Not a perfect test since I changed two conditions:
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. |
Beta Was this translation helpful? Give feedback.
-
|
Update: I'm absolutely a newbie and extremely embarrassed. Turns out you have to keep the shell running the My apologies. Thanks for replying so quickly. |
Beta Was this translation helpful? Give feedback.
-
|
I see :D thanks for the explanations |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
I can reproduce on MacOS too, will be fixed soon! |
Beta Was this translation helpful? Give feedback.
-
|
this will be solved in #5270, thanks! |
Beta Was this translation helpful? Give feedback.
All reactions
-
|
please let me know if you have a bug with the canary release: https://docusaurus.io/community/canary |
Beta Was this translation helpful? Give feedback.
-
|
@slorber cd "C:\Documents (no sync)\Scripts"
conda activate docs
npx @docusaurus/init@canary init test-docusauraus-2 classic
cd test-docusauraus-2
yarn startThank you! |
Beta Was this translation helpful? Give feedback.
-
|
great, thanks for the feedback ;) |
Beta Was this translation helpful? Give feedback.
This comment has been hidden.
This comment has been hidden.
This comment has been hidden.
This comment has been hidden.
-
|
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 Here's a Loom which walks through the issue. |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
Final step "Build your site" (base) paul@paulpauldeMacBook-Pro my-website % npm run build
[INFO] [en] Creating an optimized production build... ✔ Client ✖ Server [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. |
Beta Was this translation helpful? Give feedback.
-
|
@Chainguys please show us the content of your page |
Beta Was this translation helpful? Give feedback.
-
|
@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. |
Beta Was this translation helpful? Give feedback.
-
|
ah ok 😅 so not sure how we can improve this 🤪 maybe move the routing rules/mapping/examples at the end? 🤷♂️ |
Beta Was this translation helpful? Give feedback.
-
|
The tutorial cannot be edited. If I click the Edit button, it reports 404. |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
Oh, got it. Thanks for the heads-up. |
Beta Was this translation helpful? Give feedback.
-
|
You can follow the guide here: https://docusaurus.io/docs/installation |
Beta Was this translation helpful? Give feedback.
-
|
OK. Thank you! |
Beta Was this translation helpful? Give feedback.
-
|
Ah thanks :D didn't notice but the Netlify deployment is failing https://app.netlify.com/sites/docusaurus-tutorial
It's fixed now |
Beta Was this translation helpful? Give feedback.
-
|
Hello, great tutorial 🙌 Little feedback on the configure-the-sidebar part of the basic tutorial. When editing the Editing the 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. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for the feedback, I see how it can be confusing The sidebar is only displayed on docs it contains:
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 |
Beta Was this translation helpful? Give feedback.
-
|
Ok I see how this works now, thanks for the answer |
Beta Was this translation helpful? Give feedback.
-
No mention of site config / themeConfigOur tutorial doesn't currently show some basic things such as explaining the site config file, and in particular 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 |
Beta Was this translation helpful? Give feedback.
-
|
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! |
Beta Was this translation helpful? Give feedback.
-
|
Thanks. There's actually an example on the target page (source code) but I can see how it is confusing. Fixed in #8279 |
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
|
@ianp-its I don't understand what you mean
??? please explain what you mean by that
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? |
Beta Was this translation helpful? Give feedback.
-
|
No worries. My mistake. |
Beta Was this translation helpful? Give feedback.
-
|
Found a bug in one of the pages markdown examples Edit: will be fixed in #9696 |
Beta Was this translation helpful? Give feedback.
-
|
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). 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? |
Beta Was this translation helpful? Give feedback.
-
|
Yes you can modify the |
Beta Was this translation helpful? Give feedback.
-
|
Hi, it's not exactly a bug (more PIBKAS) but FYI, when I first created 2021-02-28-greetings.md in vscode, I mistakenly created it as a folder. Deleting the folder and creating a file didn't then get the md show. Worked as expected after re-serving the site (ctrl-c / npm start) |
Beta Was this translation helpful? Give feedback.
-
|
Hi, thanks for the great tutorial. At "Deploy from command line" section of the "Deployment" page, I needed to use |
Beta Was this translation helpful? Give feedback.
-
|
The tutorial is written under the assumption that when the user created their site, they selected JavaScript. If the user selected TypeScript, the user cannot complete all parts of the tutorial, especially the Extras. Moreover, it is extremely hard to find any documentation anywhere that explains how to switch from TypeScript to JavaScript. What's that you say? It's not possible to do that? Then there should be "dead end" documentation that explains that a site cannot be switched from one to the other. Question: Should the prompt for JavaScript over TypeScript really not mention the need to accept the default if one expects to understand Docusaurus in 5 minutes. If this caution already appears somewhere, would you please draw my attention to that location? |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for the feedback @dgcuff
Can you tell us which part of the extra tutorials, especially? From what I see, both versioning and i18n should work for the TS case too. The only quite minor difference is that the tutorial asks to modify
Where have you looked for? The embedded tutorial is only a tiny subset of Docusaurus, and you have to read the official documentation for more details.
I don't understand what you mean sorry 😅 |
Beta Was this translation helpful? Give feedback.
-
|
Well, of course, I could be wrong — perhaps the tutorial is broken for both JavaScript and TypeScript. But as written, I found two problems with the tutorial:
This sample file contains outdated information and that outdated information should be removed if it cannot be corrected (because revisionist history is bad). In the
First, the tutorial says that the config file is named If the name of the file changes, there should at a bare minimum be a note to that effect. In other words, I absolutely say “No” in response to your question, "but it seems reasonable that the user will [figure] this out?" Second, simply adding the code breaks the build. The user cannot complete the task. Now, perhaps it breaks because the user is not using the operating system you assume everyone uses, or the user has not followed your idea of the Happy Path. But that's not the user's responsibiity. It is perhaps not surprising that adding the code block as directed -- and making no other changes -- breaks the build since the final line of the config file is currently this: …which at least appears to create a conflict, if having the build break is anything to go by. The tutorial says to add the code. That’s all. It should be explicit about how to add the code, and I’m not troubleshooting for Meta for free. You tell me (in the tutorial, please, not in a forum):
I can tell you that replacing the code causes the build to break, and I can tell you that adding the code after Which issue was already raised in this forum on 2024-08-07, and yet that lack of clarity failed to prompt anyone to clarify the writing of the tutorial. Lazy writing — in a tutorial of all places — makes me move on to a better solution. It most emphatically does not make me want to spend my time debugging either the vagaries of any system nor the vagaries of its documentation, but very particularly not the part of the documentation that believes itself to be a tutorial. The most dangerous sentence in your response is “it seems reasonable that the user will…” and I do not believe that a tutorial should be anything but 100% bulletproof. Having read your reply and noted your attitude on this forum, I can see that we do not agree. Just as we don't have to agree on the philosophy on tutorial writing, I likewise do not have to invest my time in a place where I perceive the commitment to user communication to be less than rigorous. |
Beta Was this translation helpful? Give feedback.
-
I'm not sure I understand. 
I think what you thought you had to do is this: At best, we could only be a bit more precise? 🤷♂️ - and use blog: false in your Docusaurus config.
+ and use blog: false in your Docusaurus preset config.
I agree this is a problem, although it's quite easy for most users that So far you are the only one in years that complained about that, but I'm ok to improve. Would you consider
The tutorial says exactly: 
We are not saying "adding" nor replacing. We are saying that you should edit this: 
to this: 
It seems to me that both of you read the tutorial too fast and then blame us. Again, "modify" is not the same as "add" or "replace.
I'm also taking note of your attitude toward OSS developers, providing you with software for free. Please go find a better tool/community and annoy another maintainer. Your attitude is not constructive either, and after reading this wall of text, I'm also bitter that I spent time trying to answer you. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
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.
Beta Was this translation helpful? Give feedback.
All reactions