facebook / docusaurus Goto Github PK
View Code? Open in Web Editor NEWEasy to maintain open source documentation websites.
Home Page: https://docusaurus.io
License: MIT License
Easy to maintain open source documentation websites.
Home Page: https://docusaurus.io
License: MIT License
I'm running into a max call stack error for what I assume are deeply nested modules - I haven't really done anything outside of the default setup, so I'm assuming this is pretty easy to hit. Makes it so I'm unable to use docusaurus-start
.
RangeError: Maximum call stack size exceeded
at /reason-react/website/node_modules/docusaurus/lib/server/server.js:38:30
at Array.forEach (<anonymous>)
at traverse (/reason-react/website/node_modules/docusaurus/lib/server/server.js:38:22)
at /reason-react/website/node_modules/docusaurus/lib/server/server.js:39:11
at Array.forEach (<anonymous>)
at traverse (/reason-react/website/node_modules/docusaurus/lib/server/server.js:38:22)
at /reason-react/website/node_modules/docusaurus/lib/server/server.js:39:11
at Array.forEach (<anonymous>)
at traverse (/reason-react/website/node_modules/docusaurus/lib/server/server.js:38:22)
at /reason-react/website/node_modules/docusaurus/lib/server/server.js:39:11
headerLinksInternal
and headerLinksExternal
should be replaced with one array in siteConfig: headerLinks
.
Each headerLink is one of the following:
{
doc: 'foo',
label: 'Foo Doc',
}
{
page: 'foo/bar',
label: 'Foo Page',
}
This is the page located at website/pages/[en/]foo/bar.js
{
href: 'https://github.com/facebookexperimental/Docusaurus',
label: 'GitHub',
external: true,
}
Specifies the location of the search box in the header
{search: true}
The following warning can be seen in the console when a page is served by Docusaurus:
Warning: Failed Context Types: Calling PropTypes validators directly is not supported by the `prop-types` package. Use `PropTypes.checkPropTypes()` to call them. Read more at http://fb.me/use-check-prop-types Check the rend
This is a build file and I should not be encouraged to commit it
It looks like blog posts without <!--truncate-->
comments still show a Read More
link even though they are shown in entirety in the /blog page.
It'd be great to supply yarn
instructions in addition to or in place of npm
instructions. Most of this stuff maps directly between the two, but things like saving dev dependencies, yarn
wants this to be written into the package.json
file.
It seems to break at 1024px; should it rather be 736px?
core/Footer.js
has a GitHub button that links to https://github.com/deltice/test-site by default. The user will already need to configure their repo URL in siteConfig.js, so I wonder if we can just default to using that here.
In this issue I want to collect some ideas for improving our fenced code block widget. 1.0 will launch without this.
(There may be other ideas for features to implement in this issue facebook/react#10991)
Instead of Next ->
, be Name-Of-Next-Doc ->
Docusaurus is not starting up for me on a handful of demo sites. I was able to repro on a clean new project.
mkdir docusample
cd docusample
mkdir website
touch website/package.json
website/package.json
with the following:{
"scripts": {
"start": "docusaurus-start",
"build": "docusaurus-build",
"publish-gh-pages": "docusaurus-publish",
"examples": "docusaurus-examples"
},
"devDependencies": {
"docusaurus": "[email protected]:facebookexperimental/Docusaurus.git#63e3e311170fb5a8d8ae4efbd9f3d7b56f72887b"
}
}
Note that this checks out a particular commit. I was able to reproduce the issue by pulling in docusaurus from master as well (by omitting the commit-ish string), but I am including this particular commit as it appears this is where the regression was introduced.
npm run examples
npm start
Website is up and running at port 3000
The following output is seen on the console:
$ npm start
> @ start /Users/hramos/git/examples/docusample/website
> docusaurus-start
/Users/hramos/git/examples/docusample/website/node_modules/docusaurus/lib/server/server.js:183
<DocsLayout metadata={metadata} language={language} config={siteConfig}>
^
SyntaxError: Unexpected token <
at createScript (vm.js:74:10)
at Object.runInThisContext (vm.js:116:10)
at Module._compile (module.js:533:28)
at Module._extensions..js (module.js:580:10)
at Object.require.extensions.(anonymous function) [as .js] (/Users/hramos/git/examples/docusample/website/node_modules/babel-register/lib/node.js:152:7)
at Module.load (module.js:503:32)
at tryModuleLoad (module.js:466:12)
at Function.Module._load (module.js:458:3)
at Module.require (module.js:513:17)
at require (internal/module.js:11:18)
When the full link is provided (http://localhost:3000/
) it can be clickable in some circumstances, like with cmd-click
I definitely see the advantage of setting up CI deploys, but it would be really nice to be able to run docusaurus-publish --manual
or docusaurus-publish --local
and deploy from your own machine with your github identity. I think this would lower the barrier greatly for getting a site up and getting it running.
Port 3000 doesn't work in all environments. It'd be great to be able to override this somehow.
The example files are being copied to YOUR_SITE/website/YOUR_SITE/website/node_modules/docusaurus/examples
instead of YOUR_SITE/website
.
Consider a new plain example site, docusample
, with a single package.json file:
$ pwd
/Users/hramos/git/examples/docusample/website
$ ls -ltras
total 8
8 -rw-r--r-- 1 hramos THEFACEBOOK\Domain Users 314 Aug 7 14:31 package.json
0 drwxr-xr-x 4 hramos THEFACEBOOK\Domain Users 136 Aug 7 14:51 ..
0 drwxr-xr-x 4 hramos THEFACEBOOK\Domain Users 136 Aug 7 14:52 .
It's contents are:
{
"scripts": {
"start": "docusaurus-start",
"build": "docusaurus-build",
"publish-gh-pages": "docusaurus-publish",
"examples": "docusaurus-examples"
},
"devDependencies": {
"docusaurus": "[email protected]:facebookexperimental/Docusaurus.git"
}
}
Running npm run examples
will place all the placeholder files inside YOUR_SITE/website/YOUR_SITE/website/node_modules/docusaurus/examples/
instead of YOUR_SITE/website/
itself:
$ pwd
/Users/hramos/git/examples/docusample/website
$ ls -ltras
total 8
8 -rw-r--r-- 1 hramos THEFACEBOOK\Domain Users 314 Aug 7 14:31 package.json
0 drwxr-xr-x 4 hramos THEFACEBOOK\Domain Users 136 Aug 7 14:51 ..
0 drwxr-xr-x 258 hramos THEFACEBOOK\Domain Users 8772 Aug 7 14:55 node_modules
0 drwxr-xr-x 3 hramos THEFACEBOOK\Domain Users 102 Aug 7 14:55 docusample
0 drwxr-xr-x 5 hramos THEFACEBOOK\Domain Users 170 Aug 7 14:55 .
$ ls -ltras docusample/website/node_modules/docusaurus/examples/
total 16
0 drwxr-xr-x 3 hramos THEFACEBOOK\Domain Users 102 Aug 7 14:55 static
8 -rw-r--r-- 1 hramos THEFACEBOOK\Domain Users 2481 Aug 7 14:55 siteConfig.js
8 -rw-r--r-- 1 hramos THEFACEBOOK\Domain Users 174 Aug 7 14:55 sidebar.json
0 drwxr-xr-x 3 hramos THEFACEBOOK\Domain Users 102 Aug 7 14:55 pages
0 drwxr-xr-x 3 hramos THEFACEBOOK\Domain Users 102 Aug 7 14:55 core
0 drwxr-xr-x 3 hramos THEFACEBOOK\Domain Users 102 Aug 7 14:55 ..
0 drwxr-xr-x 7 hramos THEFACEBOOK\Domain Users 238 Aug 7 14:55 .
When translating .md files, the titles also get put into en.json. This causes duplicate entries in crowdin.
See:
https://crowdin.com/translate/reason-react/4/en-enud
https://crowdin.com/translate/reason-react/25/en-enud#q=Working+with+Children
for duplicates.
"Cannot GET /docusaurus/docs/en/getting-started.html"
A personal site like mine could benefit from a "start at blog" feature.
How it would work:
Set starting page as /blog --> reroute /index to /blog
Could also render the /blog in /index.html
These lines will best case scenario throw a cryptic error, worst case scenario not copy your files correctly:
https://github.com/facebookexperimental/Docusaurus/blob/master/lib/server/generate.js#L342-L344
Try yarn build
with a file called staticRedirect.js
for a repro.
I added a valid item to the sidebar and then did docusaurus-write-translations
(not sure if this part's relevant). When I go to the doc page it gives the typical error:
Error: Improper sidebars.json file. Make sure that documents with the ids specified in sidebars.json exist and that no ids are repeated
I've found out that it's because I downloaded all the translations through crowdin, which adds a new translated_docs
folder and many json files into I18n
. These aren't updated. Removing the folder and the other translation json files in i18n
solves the problem.
Use this to come up with issues and items we want to close during this docathon
It seems to include the '/en/', even though it is not inside an en folder
When someone installs Docusaurus via yarn
or npm
, we need to do one or maybe two things re: licensing:
Remove the license headers from the code that is generated in website
for the site that uses Docusaurus since it points to the actual Docusaurus GitHub repo license which may not be applicable to the site using Docusaurus.
Add our Examples license to the examples
directory. We should discuss if this is the right thing to do.
The React Native blog has some additional frontmatter tags. One of those allows a blog post to display the author's profile picture. See https://github.com/facebook/react-native/blob/master/blog/2017-08-30-react-native-monthly-3.md for an example.
I'll add this functionality to Docusaurus.
Right now
TypeError: Cannot read property 'language' of undefined
at /Users/joelm/dev/Docusaurus-primary/lib/server/server.js:160:22
at Layer.handle [as handle_request] (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/layer.js:95:5)
at next (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/route.js:137:13)
at Route.dispatch (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/route.js:112:3)
at Layer.handle [as handle_request] (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/layer.js:95:5)
at /Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/index.js:281:22
at Function.process_params (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/index.js:335:12)
at next (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/index.js:275:10)
at expressInit (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/middleware/init.js:40:5)
at Layer.handle [as handle_request] (/Users/joelm/dev/Docusaurus-primary/node_modules/express/lib/router/layer.js:95:5)
Probably could do a check and give a message like "Did you remove the default document and forget to remove from siteConfig.js"???
For example - 2017-09-01-0.2.4.md
will try to generate /blog/2017/09/01/0-2-4.html
, but when loading the page using docusaurus-start
there is an error message that looks like:
Error: ENOENT: no such file or directory, open '/path/to/project/website/blog/2017-09-01-0-2-4.md'
When Docusaurus is running, the following warning can be seen in the console when a page is accessed:
Warning: Each child in an array or iterator should have a unique "key" prop. Check the render method of `Marked`. See https://fb.me/react-warning-keys for more information.
in p (created by Marked)
in Marked (created by GridBlock)
in h2 (created by GridBlock)
in div (created by GridBlock)
in div (created by GridBlock)
in div (created by GridBlock)
in GridBlock (created by Index)
in div (created by Container)
in div (created by Container)
in Container (created by Index)
in div (created by Index)
in div (created by Index)
in Index
in div (created by Site)
in body (created by Site)
in html (created by Site)
in Site
Fixing this warning is straightforward in React code, but notice that it's coming from marked.js
. If I understand this correctly, we're generating HTML from Markdown and placing the output inside a React component. The generated HTML lacks the keys props, causing this warning to show.
We're using a local copy of marked.js
, and not the one from npm, IIRC.
Adding a new translation tag like <translate>hello</translate>
without running docusaurus-write-translations
results in a cryptic runtime error when running docusaurus-start
. Would be nice to get explicit instructions on next steps.
TypeError: Cannot read property 'replace' of undefined
at parseEscapeSequences (/path/to/website/node_modules/docusaurus/lib/server/translate.js:16:10)
at translate (/path/to/website/node_modules/docusaurus/lib/server/translate.js:32:10)
at Index.render (/path/to/website/node_modules/docusaurus/lib/pages/en/tempindex.js:204:15)
at /path/to/website/node_modules/react-dom/lib/ReactCompositeComponent.js:793:21
at measureLifeCyclePerf (/path/to/website/node_modules/react-dom/lib/ReactCompositeComponent.js:73:12)
at ReactCompositeComponentWrapper._renderValidatedComponentWithoutOwnerOrContext (/path/to/website/node_modules/react-dom/lib/ReactCompositeComponent.js:792:25)
at ReactCompositeComponentWrapper._renderValidatedComponent (/path/to/website/node_modules/react-dom/lib/ReactCompositeComponent.js:819:32)
at ReactCompositeComponentWrapper.performInitialMount (/path/to/website/node_modules/react-dom/lib/ReactCompositeComponent.js:359:30)
at ReactCompositeComponentWrapper.mountComponent (/path/to/website/node_modules/react-dom/lib/ReactCompositeComponent.js:255:21)
at Object.mountComponent (/path/to/website/node_modules/react-dom/lib/ReactReconciler.js:43:35)
We should be able to write a script that creates the website directory, adds the package.json
info and does the npm
or yarn
install.
@caabernathy ran into a problem where permalinks are not working and I ran a test and found similar non-working behavior.
See internal Docusaurus post from @caabernathy
I noticed that the React Native site looks weird on mobile. I'll come back to this task later with examples.
If you have a page that you don't want to have the default design for the site, but it still has CSS files, and you put those CSS files in static, those files will possibly clobber the CSS files of the site.
To fix, maybe...
have a flag that tells Docusaurus which are the canonical CSS files that should be used when rendering. While the others will be ignored.
@caabernathy ran into the problem where she was running on 3000 for another app, and we got confused why Docusaurus would not load.
In my siteConfig.json
:
/* header links for links outside the site */
headerLinksExternal: [
{
section: "buck",
href: "https://buckbuild.com",
text: "Buck"
},
{
section: "github",
href: "https://github.com/deltice/test-site",
text: "GitHub"
}
],
Results in this HTML being generated:
<li><a href="https://buckbuild.com" class=""></a></li><li><a href="https://github.com/deltice/test-site" class="">GitHub</a></li>
While the node was created, it doesn't have the text in it. Order doesn't seem to matter; GitHub is always printed, and Buck isn't.
We need to figure out a way to make Docusaurus pluggable.
There are features we are not going to support that some people may want. How can we make it easy for folks to add those features.
This should be valid
Feature Request:
Allow defining a permalink in post and doc markdown frontmatter.
Sidebar links send a user to url#content
. Not sure what the rationale was for doing this, but we shouldn't.
Seems to not work entirely
.... maybe with Jest.
That way we can regression test changes, etc.
Currently in the translation documentation it's recommended that you add a line like: "crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID; export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml upload sources --auto-update -b master",
to your package.json. What is crowdin-cli
? It doesn't work the the npm i crowdin-cli
package, and the recommended crowdin cli uses the crowdin
command. Is there a different package I should be looking at?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.