https://github.com/casbin/casbin-website
Deprecated! Please use v2 docs site: https://github.com/casbin/casbin-website-v2 | The v1 docs website for Casbin
https://github.com/casbin/casbin-website
casbin docs documentation docusaurus jcasbin node-casbin
Last synced: 11 months ago
JSON representation
Deprecated! Please use v2 docs site: https://github.com/casbin/casbin-website-v2 | The v1 docs website for Casbin
- Host: GitHub
- URL: https://github.com/casbin/casbin-website
- Owner: casbin
- License: apache-2.0
- Created: 2018-08-12T03:03:57.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-07-11T09:50:55.000Z (over 2 years ago)
- Last Synced: 2024-10-29T22:37:44.131Z (over 1 year ago)
- Topics: casbin, docs, documentation, docusaurus, jcasbin, node-casbin
- Language: JavaScript
- Homepage: https://v1.casbin.org
- Size: 2.29 MB
- Stars: 39
- Watchers: 4
- Forks: 132
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/Contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# [v1.casbin.org](https://v1.casbin.org/) [](https://github.com/casbin/casbin-website/actions)
The site configuration and documentation powering Casbin's website: https://v1.casbin.org
## Getting started
### Prerequisites
1. Git
1. Node: install version 6.2.2 or greater. Node v8 would be ideal.
1. Yarn: See [Yarn Installation](https://yarnpkg.com/lang/en/docs/install/)
1. Docusaurus: Run `yarn global add docusaurus-init` or `npm install --global docusaurus-init`
### Installation
1. `git clone https://github.com/casbin/casbin-website` to download source code.
1. `cd casbin-website` to go into the project root.
1. `cd website` to go into the website portion of the project.
1. `yarn` to install the website's npm dependencies (or `npm install`, if not using Yarn).
### Running locally
1. `yarn start` to start the development server (powered by Docusaurus) (or `npm start`, if not using Yarn).
1. open `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://v1.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:
1. `yarn run publish-gh-pages` to publish the site to GitHub pages: https://github.com/casbin/casbin.github.io (aka https://v1.casbin.org).
# Overview
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 `docs/` directory.
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](https://docusaurus.io). The website configuration can be
found in the `website/` directory. Visit the Docusaurus website to learn more
about all the available configuration options.
## Directory structure
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
```
## Documentation sources
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
markdown files.
### Versioned 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 `docs/` and `website/sidebars.json` files will be copied
over to the corresponding location within `website/versioned_docs/` and
`website/versioned_sidebars/`.
> Do not edit the auto-generated files within `versioned_docs/` or
> `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
1. `cd casbin-website` to go into the project root
1. `cd website` to go into the website portion of the project
1. Run `yarn version ` where `` is the new version being
released.
## Website configuration
The main config file for the website can be found at `website/siteConfig.js`.
This file tells Docusaurus [how to build the website](http://docusaurus.io/docs/en/site-config.html).
Edits to this file are rarely necessary.
The `pages/` subdirectory contains the Casbin components that make up the
non-documentation pages of the site, such as the homepage.
The `showcase.json` file contains the list of users that are highlighted in the
Casbin showcase.
## Contributing
### Create a branch
1. `git checkout master` from any folder in your local `casbin-website` repository.
1. `git pull origin master` to ensure you have the latest main code.
1. `git checkout -b the-name-of-my-branch` (replacing `the-name-of-my-branch`
with a suitable name) to create a branch.
### Make the change
1. Follow the [Running locally](#running-locally) instructions.
1. Save the files and check in the browser. Some changes may require a server restart.
1. Changes to `/docs` will only be visible in the latest version of the documentation (master).
open `http://localhost:3000/casbin/versions.html` to see other versions.
### Test the change
1. If possible, test any visual changes in all latest versions of common
browsers, on both desktop and mobile.
### Push it
1. Run `yarn prettier` to ensure your changes are consistent with other files in
the repo
1. `git add -A && git commit -m "My message"` (replacing `My message` with a
commit message, such as `Fixed header logo on Android`) to stage and commit
your changes
1. `git push my-fork-name the-name-of-my-branch`
1. Go to the
[casbin-website repo](https://v1.casbin.org)
and you should see recently pushed branches.
1. Follow GitHub's instructions.
1. If possible, include screenshots of visual changes.
---
## Translation
[Crowdin](https://crowdin.com/project/casbin) is used for Casbin website's translation. You can contribute to the translation of your proficient languages on that.
### Build the translation project locally
Please contact the Casbin team for manager access on Crowdin.
### Manually trigger Crowdin [DEPRECATED]
- Install Crowdin CLI:
https://support.crowdin.com/cli-tool/
- Setup environment variable:
```
CROWDIN_DOCUSAURUS_API_KEY = XXX
```
- Upload:
```
crowdin --config ../crowdin.yaml upload sources --auto-update -b master
```
- Download:
```
crowdin --config ../crowdin.yaml download -b master
```
> Noting that the translation of the official website will update after a Pull Request is merged
## License
Casbin is [Apache licensed](./LICENSE).
Casbin documentation is [Creative Commons licensed](./LICENSE-docs).