Coder Social home page Coder Social logo
docusaurus

facebook / docusaurus Goto Github PK

View Code? Open in 1sVSCode Editor NEW
34.5K 325.0 4.9K 226.87 MB

Easy to maintain open source documentation websites.

Home Page: https://docusaurus.io

License: MIT License

JavaScript 1.18% CSS 1.94% TypeScript 96.85% EJS 0.03%
documentation website javascript react open-source hacktoberfest

docusaurus's Introduction

Docusaurus

Docusaurus

Twitter Follow npm version GitHub Actions status PRs Welcome Discord Chat code style: prettier Tested with Jest Gitpod Ready-to-Code Netlify Status CI Score Deploy with Vercel Deploy to Netlify

We are working hard on Docusaurus v2. If you are new to Docusaurus, try using the new version instead of v1. See the Docusaurus v2 website for more details.

Docusaurus v1 doc is available at v1.docusaurus.io and code is available on branch docusaurus-v1

Introduction

Docusaurus is a project for building, deploying, and maintaining open source project websites easily.

Short on time? Check out our 5-minute tutorial ⏱️!

Tip: use docusaurus.new to test Docusaurus immediately in a playground.

  • Simple to Start

Docusaurus is built in a way so that it can get running in as little time as possible. We've built Docusaurus to handle the website build process so you can focus on your project.

  • Localizable

Docusaurus ships with localization support via CrowdIn. Empower and grow your international community by translating your documentation.

  • Customizable

While Docusaurus ships with the key pages and sections you need to get started, including a home page, a docs section, a blog, and additional support pages, it is also customizable as well to ensure you have a site that is uniquely yours.

Installation

Use the initialization CLI to create your site:

Read the docs for any further information.

Contributing

We've released Docusaurus because it helps us better scale and supports the many OSS projects at Facebook. We hope that other organizations can benefit from the project. We are thankful for any contributions from the community.

Code of Conduct

Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Contributing guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Docusaurus.

Beginner-friendly bugs

To help you get your feet wet and get you familiar with our contribution process, we have a list of beginner-friendly bugs that might contain smaller issues to tackle first. This is a great place to get started.

Contact

We have a few channels for contact:

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 Become a backer

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor

License

Docusaurus is MIT licensed.

The Docusaurus documentation (e.g., .md files in the /docs folder) is Creative Commons licensed.

Special thanks

BrowserStack logo

BrowserStack supports us with free access for open source.

Rocket Validator logo

Rocket Validator helps us find HTML markup or accessibility issues.

docusaurus's People

Contributors

lex111 avatar endiliey avatar slorber avatar Josh-Cena avatar yangshun avatar JoelMarcey avatar deltice avatar ericnakagawa avatar dependabot[bot] avatar SamChou19815 avatar Simek avatar hramos avatar wgao19 avatar fanny avatar rickyvetter avatar armano2 avatar RDIL avatar teikjun avatar hong4rc avatar anshulrgoyal avatar italicize avatar nschonni avatar amyrlam avatar ayonious avatar pranabdas avatar ahmadalfy avatar vjeux avatar massoudmaboudi avatar forresst avatar johnnyreilly avatar

Stargazers

Piyush Pawar avatar Yun Zhang avatar sunnier avatar Culm avatar SangamSwadik avatar Bruno Oliveira avatar LGiki avatar Omar avatar Jeovani Martínez avatar Robert Scherbarth avatar Mayank Pathela avatar Aashutosh Rathi avatar Mohit Kumar Yadav avatar Nico Lindemann avatar  avatar  avatar  avatar Yousef Abdelkhaleq avatar Ranger Tsao avatar Li Ke avatar learning_accoutant avatar Max Thomson avatar Jonathan avatar Fire Cube avatar Austin Biggs avatar hakan avatar  avatar Eric  avatar Sam Sokolin avatar Low Entropy Body avatar Doug Collier avatar Mikhail avatar Tai In, Kwon avatar 1237 avatar  avatar Lopkop avatar Decyph3r avatar weiyan avatar 赤城结衣 avatar  avatar Yuki Yokotani avatar Leonid Shirmanov avatar  avatar Adepoju Oluwasegun avatar Will avatar  avatar Timothé David  avatar  avatar  avatar 123 avatar Timothy B. avatar  avatar heechang kang avatar Ed Hull avatar Ashwani avatar yzbbanban avatar Gerson Minichiello avatar Khaled Saidi avatar BingqiChen avatar Felix Wohnhaas avatar Can avatar 怪侠沈剑心 avatar Harry Wang avatar xxb avatar Tim Robbins avatar  avatar Nishanth Koganti avatar Patt O'Brien avatar Gaus Al Munir Tushar avatar Petteri Pucilowski avatar João Paulo Araújo avatar Lucas Rodrigues avatar Marius Wilms avatar Mohamed Abdel-Samie avatar Sébastien HUG DE LARAUZE avatar Omri Bar-Zik avatar Steve Parks avatar Paul Eboselume avatar Erik Brüggemann avatar Ali Balbars avatar saeed avatar  avatar  avatar Oliver avatar Ulualp avatar Chao Guo avatar  avatar Xavier Xie avatar Dokyun Lim avatar David Kariuki (DK) avatar Brendan Wenzel avatar  avatar Jinbe avatar  avatar Yutao avatar Rizky Sulistyo avatar  avatar Nguyễn Hải Nam avatar Daniel Venturini avatar  avatar

Watchers

Peter Neubauer avatar azu avatar Lalit avatar Rob Kunkle avatar Tim Post avatar yuanhong avatar Steve Parks avatar  avatar Jan Erik Solem avatar davidwei_001 avatar Forresst avatar Welber Gouveia avatar Diego Abad avatar Jandy avatar cnmade avatar  avatar 月影 avatar Yoshiyuki Ieyama avatar Ciro Nunes avatar anna mendoza avatar Andrew Imm avatar Lance He avatar Kaifeng avatar duanshuaimin avatar Oscar Trigueiros avatar tml avatar KINGZHI avatar Von Brian Layugan avatar  avatar HoNooD avatar Colin avatar  avatar hz2004 avatar heisonyee avatar  avatar Sébastien Lorber avatar Archer (炽宇) avatar Sreenivas Vemulapalli avatar timelyportfolio avatar James Cloos avatar poldyaev avatar Trimikha Valentius avatar  avatar Mahesh Ruparel avatar Easter avatar Volkan Özçelik avatar Mark Conover avatar  avatar dofstar avatar  avatar Phillip Ressler avatar Wilfried Santer avatar  avatar Daniel Zimpel Wayhs avatar vinit khandagle avatar Justin Hachemeister avatar Karthik Sripal J avatar 苏道波 avatar echo avatar Brian Johnson avatar Juri avatar latyas avatar Chris Brody avatar Maria Stellini avatar StarMan avatar Edward Xie avatar  avatar zhouguoqing917 avatar Ak Ugur avatar 蔡正海 avatar Mostefaoui Mohamed Anes avatar Jerome Holman avatar Cheng Lou avatar Nadiia avatar  avatar Andrei Arkhipov avatar  avatar Vitalie Glodeanu avatar  avatar  avatar  avatar Artak avatar Tuna Aras avatar  avatar leon avatar Mathieu Bressolle-Chataigner avatar Yuandong Tian avatar Pim Hwang avatar JerryZH.Chen avatar Alin Porumb avatar Dondrey Taylor avatar Muhammet Ali Köker avatar Ganesh Bhat avatar Joel Marcey avatar  avatar  avatar Kunal Batra avatar wurenhai avatar ZiMo(熊文财) avatar Prydaz avatar

docusaurus's Issues

max callstack error

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

Docathon August 2017: Master Issue List

Use this to come up with issues and items we want to close during this docathon

  • Logo (@ericnakagawa)
  • Sidebar content (see below for details)
  • Landing Page - Includes icons/graphics, CSS (@ericnakagawa)
  • Footer
  • Help Page
  • Site look and feel - (@ericnakagawa)
  • Site launch (Cloudflare, SSL, nameservers) (@JoelMarcey)
  • CircleCI or Travis to actually publish the docusaurus.io website
  • Remove noindex meta tag from Head.js before launch (@JoelMarcey)
  • Finalize Jest PR (@ericnakagawa)

Runtime error when adding new translation string.

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)

Adding additional external links doesn't appear to work

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.

Feature Request - Blog mode

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

Website generation fails with SyntaxError: Unexpected token < | <DocsLayout ... >

Docusaurus is not starting up for me on a handful of demo sites. I was able to repro on a clean new project.

Steps to reproduce

  1. Create a brand new project. For example:
mkdir docusample 
cd docusample
mkdir website
touch website/package.json
  1. Update 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.

  1. Populate samples:
npm run examples
  1. Start the website server:
npm start

Expected Results

Website is up and running at port 3000

Actual Results

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)

Read More link on blog posts

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.

Clobbering CSS files for external pages

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.

Licensing for installs of Docusaurus

When someone installs Docusaurus via yarn or npm, we need to do one or maybe two things re: licensing:

  1. 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.

  2. Add our Examples license to the examples directory. We should discuss if this is the right thing to do.

`yarn` install instructions

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.

Better crowdin command documentation.

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?

Feature: Pluggable infrastructure

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.

Remove react-warning-keys

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.

docusaurus-examples places examples in wrong subdirectory

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 .

Sidebars fails after adding a new item; not reflected in `i18n` and `translated_docs`

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.

[feature request] manual deploy

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.

Better error message if remove default doc

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"???

Blog posts with . in file name don't get loaded correctly

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'

Fix mobile layout

I noticed that the React Native site looks weird on mobile. I'll come back to this task later with examples.

[Enhancement] Improved code blocks

In this issue I want to collect some ideas for improving our fenced code block widget. 1.0 will launch without this.

  • Language toggling
    A good example of this can be found in the Parse docs.
  • Sub-language toggles
    (e.g. ES6, ES5)
  • Line highlighting
    Support ```javascript{3,5-7} syntax for highlighting (#105 @rickyvetter)

(There may be other ideas for features to implement in this issue facebook/react#10991)

API Change: siteConfig headerLinks

headerLinksInternal and headerLinksExternal should be replaced with one array in siteConfig: headerLinks.

Each headerLink is one of the following:

Link to Doc:

{
  doc: 'foo',
  label: 'Foo Doc',
}

Link to Page:

{
  page: 'foo/bar',
  label: 'Foo Page',
}

This is the page located at website/pages/[en/]foo/bar.js

Manual/External Link

{
  href: 'https://github.com/facebookexperimental/Docusaurus',
  label: 'GitHub',
  external: true,
}

Search Box

Specifies the location of the search box in the header

{search: true}

Remove use-check-prop-types warning

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

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.