The site configuration and documentation powering Casbin's website: https://casbin.org
- Node: install version 6.2.2 or greater. Node v8 would be ideal.
- Yarn: See Yarn Installation
- Docusaurus: Run
yarn global add docusaurus-initor
npm install --global docusaurus-init
git clone https://github.com/casbin/casbin-websiteto download source code.
cd casbin-websiteto go into the project root.
cd websiteto go into the website portion of the project.
yarnto install the website's npm dependencies (or
npm install, if not using Yarn).
yarn startto start the development server (powered by Docusaurus) (or
npm start, if not using Yarn).
http://localhost:3000/to open the site in your favorite browser.
Publish manually (optional)
Whenever a new commit lands in
master, the change will be automatically
published to: https://casbin.org. However, if you want to deploy the site manually,
make sure you have
write access to: https://github.com/casbin/casbin.github.io,
and use the following instruction:
yarn run publish-gh-pagesto publish the site to GitHub pages: https://github.com/casbin/casbin.github.io (aka https://casbin.org).
If you're here because you would like to contribute an edit or addition to the
docs, you'll probably want to take a look at the
To edit the internals of how the site is built, you may want to get familiarized
with how the site is built. The Casbin website is a static site generated
using Docusaurus. The website configuration can be
found in the
website/ directory. Visit the Docusaurus website to learn more
about all the available configuration options.
The following is a high-level overview of relevant files and folders.
casbin-website/ ├── docs/ │ ├── assets/ │ ├── accessibility.md │ └── ... └── website/ ├── blog/ │ ├── assets/ │ ├── 2015-03-26-casbin-bringing-modern-web-techniques-to-mobile.md │ └── ... ├── core/ ├── pages/ │ └── en/ │ ├── ... │ ├── index.js │ └── ... ├── static/ │ ├── css/ │ ├── img/ │ └── js/ ├── versioned_docs/ │ ├── version-0.5/ │ └── ... ├── versioned_sidebars/ │ ├── version-0.5-sidebars.json │ └── ... ├── showcase.json ├── sidebars.json ├── siteConfig.js └── versions.json
As mentioned above, the
docs/ folder contains the source files for all of the
docs in the Casbin website. In most cases, you will want to edit the files
within this directory. If you're adding a new doc or you need to alter the order
the docs appear in the sidebar, take a look at the
sidebars.json file in the
website/ directory. The sidebars file contains a list of document ids that
should match those defined in the header metadata (aka frontmatter) of the docs
The Casbin website is versioned as to allow users to go back and see the
API reference docs for any given release. A new version of the website is
generally made whenever there is a new Casbin release. When this happens,
any changes made to the
website/sidebars.json files will be copied
over to the corresponding location within
Do not edit the auto-generated files within
versioned_sidebars/unless you are sure it is necessary. Edits made to older versions will not be propagated to newer versions of the docs.
Docusaurus keeps track of the list of versions for the site in the
website/versions.json file. The ordering of the versions in this file should
be in reverse chronological order.
Cutting a new version
cd casbin-websiteto go into the project root
cd websiteto go into the website portion of the project
yarn version <version>where
<version>is the new version being released.
The main config file for the website can be found at
This file tells Docusaurus how to build the website.
Edits to this file are rarely necessary.
pages/ subdirectory contains the Casbin components that make up the
non-documentation pages of the site, such as the homepage.
showcase.json file contains the list of users that are highlighted in the
Create a branch
git checkout masterfrom any folder in your local
git pull origin masterto ensure you have the latest main code.
git checkout -b the-name-of-my-branch(replacing
the-name-of-my-branchwith a suitable name) to create a branch.
Make the change
- Follow the Running locally instructions.
- Save the files and check in the browser. Some changes may require a server restart.
- Changes to
/docswill only be visible in the latest version of the documentation (master).
http://localhost:3000/casbin/versions.html to see other versions.
Test the change
- If possible, test any visual changes in all latest versions of common browsers, on both desktop and mobile.
yarn prettierto ensure your changes are consistent with other files in the repo
git add -A && git commit -m "My message"(replacing
My messagewith a commit message, such as
Fixed header logo on Android) to stage and commit your changes
git push my-fork-name the-name-of-my-branch
- Go to the casbin-website repo and you should see recently pushed branches.
- Follow GitHub's instructions.
- If possible, include screenshots of visual changes.
Crowdin is used for Casbin website's translation.
Manually trigger Crowdin
- Install Crowdin CLI:
- Setup environment variable:
CROWDIN_DOCUSAURUS_API_KEY = XXX
crowdin --config ../crowdin.yaml upload sources --auto-update -b master
crowdin --config ../crowdin.yaml download -b master
Casbin is Apache licensed.
Casbin documentation is Creative Commons licensed.