/discoverthreejs-site

Repo for the book Discover three.js!

Primary LanguageJavaScript

Welcome to Discover three.js!

Languages: English (this file), 中文.

This is the public repo for the book Discover three.js.

Pull requests are welcome, especially for:

  • Keeping the book up to date with new three.js releases.
  • Errata in the text or code examples.
  • Any other bugs, browser or CSS issues.

Search through the markdown folder for "TODO" if you're looking for inspiration ^_^

For larger contributions, please get in touch before making changes - you can open a discussion or issue on this repo.

Developer Guide

Here is the process for building and viewing the book.

Prerequisites: Node.js, Hugo

  1. Clone or download the repo
  2. Download the Hugo extended binary for your system here and place it in the project root. Tested with Hugo V0.92.0 (*)
  3. Run npm install
  4. Run npm start
  5. Go to http://localhost:1313/ to view the site. You may need to make sure this port is open in your firewall.

* On linux systems you may need to set the ./hugo file as executable using chmod +x ./hugo.

Technical Details

The book is built with Hugo, and this repo follows a fairly typical folder structure for a Hugo project, although the content/ folder has been renamed to markdown/. If you want to make changes, refer to the Hugo docs.

Important folders

  • markdown - all the words in the book are contained here.
  • assets/src - JS source code.
  • assets/scss - SCSS styles for the book are here.
  • static - all static files such as figures, fonts, models, textures, images, and favicons are here.
  • static/examples - the code for the IDE examples are here. Each example is a World - for examples: static/examples/worlds/first-steps/first-scene contains the example for the chapter First Scene. See static/examples/README.md for more details.
  • /public - files generated by Hugo with the command npm run production will go here. By default, in development Hugo renders files into memory, however, it can be useful to generate the files if you need to examine them.

Notes

  • Hugo Pipes are used to build SCSS and JS assets. This means the Hugo extended version must be used.
  • Running npm start will take several seconds to bundle all the files so please be patient. However, once the server is running, updates should take just a few milliseconds.

LICENSE

Code License

All code in this repo (including code sample in the text and any source code in the /assets folder) is covered by the MIT license. You are free to use it however you like, including in commercial applications. This does not cover any included third party libraries which have their own license.

Text License

Text from the book may not be reproduced without permission outside of this repo and the website discoverthreejs.com. You are free to fork the repo to make changes to the text but you are not allowed to host the text on another site (such as your own blog or tutorial site).