-
-
Notifications
You must be signed in to change notification settings - Fork 72
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
53967d3
commit ba4eae5
Showing
1 changed file
with
65 additions
and
157 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,203 +1,111 @@ | ||
| # [casbin.org](https://casbin.org/) [](https://github.com/casbin/casbin-website/actions) | ||
| The site configuration and documentation powering Casbin's website: https://casbin.org | ||
| # [casbin.io](https://casbin.io) [](https://github.com/casbin/casbin-website-v2/actions/workflows/master.yml) | ||
|
|
||
| ## Getting started | ||
| The configuration and documentation of Casbin website: <https://casbin.io/>. | ||
|
|
||
| ### Prerequisites | ||
| Casbin website is built using [Docusaurus](https://docusaurus.io/), you can get the PDF at [Release](https://github.com/casbin/casbin-website-v2/releases/tag/pdf). | ||
|
|
||
| 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` | ||
| ## Get Started | ||
|
|
||
| ### Installation | ||
| ### Requirements | ||
|
|
||
| 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). | ||
| 1. [Git](https://git-scm.com/downloads) | ||
| 2. [Node.js](https://nodejs.org/en/download/)：v16.14 or above | ||
| 3. [Yarn](https://classic.yarnpkg.com/en/docs/install): please use Yarn 1 | ||
|
|
||
| ### Running locally | ||
| ### 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. | ||
| 1. `git clone https://github.com/casbin/casbin-website-v2.git` | ||
| 2. `cd casbin-website-v2` | ||
| 3. `yarn`: install dependencies. | ||
| 4. `yarn start`: starting the development server. | ||
|
|
||
| ### 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: | ||
|
|
||
| 1. `yarn run publish-gh-pages` to publish the site to GitHub pages: https://github.com/casbin/casbin.github.io (aka https://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 | ||
| ## Contributing | ||
|
|
||
| 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. | ||
| You can contribute to the documentation site in different ways: [Documentation Writing](#documentation-writing), [Translation](#translation), [Website Development](#website-development). | ||
|
|
||
| ### Versioned docs | ||
| ### Documentation Writing | ||
|
|
||
| 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/`. | ||
| For the configuration of the sidebar, you can refer to [Sidebar](https://docusaurus.io/docs/sidebar). | ||
|
|
||
| > 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. | ||
| For the features that you may use when writing documents, please refer to [Markdown Features](https://docusaurus.io/docs/markdown-features). | ||
|
|
||
| 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. | ||
| A standard document should look like this: | ||
|
|
||
| #### Cutting a new version | ||
| ````md | ||
| --- | ||
| title: Title | ||
| description: description | ||
| keywords: [keyword1, keyword2] | ||
| --- | ||
|
|
||
| 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 <version>` where `<version>` is the new version being | ||
| released. | ||
| ## Headers | ||
|
|
||
| ## Website configuration | ||
| Only h2 and h3 will be in the TOC by default. | ||
|
|
||
| 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. | ||
| ### h3 | ||
|
|
||
| The `pages/` subdirectory contains the Casbin components that make up the | ||
| non-documentation pages of the site, such as the homepage. | ||
| content | ||
|
|
||
| The `showcase.json` file contains the list of users that are highlighted in the | ||
| Casbin showcase. | ||
| #### h4 | ||
|
|
||
| ## Contributing | ||
| content | ||
|
|
||
| ### 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. | ||
| #### Caution | ||
|
|
||
| ### Make the change | ||
| ##### Admonitions | ||
|
|
||
| 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). | ||
| You can add [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) in the documentation, but please leave two blank lines like this: | ||
|
|
||
| open `http://localhost:3000/casbin/versions.html` to see other versions. | ||
| ```md | ||
| :::info Title | ||
|
|
||
| ### Test the change | ||
| Title is optional | ||
|
|
||
| 1. If possible, test any visual changes in all latest versions of common | ||
| browsers, on both desktop and mobile. | ||
| ::: | ||
| ``` | ||
|
|
||
| ### Push it | ||
| ##### JSX | ||
|
|
||
| 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://casbin.org) | ||
| and you should see recently pushed branches. | ||
| 1. Follow GitHub's instructions. | ||
| 1. If possible, include screenshots of visual changes. | ||
| You can use JSX in documents, such as the [Tabs](https://docusaurus.io/docs/markdown-features/tabs) component provided by Docusaurus, but to prevent Crowdin from breaking the code ([mdx-solutions](https://docusaurus.io/docs/i18n/crowdin#mdx-solutions)), please wrap the JSX code: | ||
|
|
||
| --- | ||
| `````md | ||
|
|
||
| ## Translation | ||
| ````mdx-code-block | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| [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. | ||
| <Tabs> | ||
| <TabItem value="go" label="Go"> | ||
|
|
||
| ### Build the translation project locally | ||
| Please contact the Casbin team for manager access on Crowdin. | ||
| content | ||
|
|
||
| ### Manually trigger Crowdin [DEPRECATED] | ||
| </TabItem> | ||
| <TabItem value="java" label="Java"> | ||
|
|
||
| - Install Crowdin CLI: | ||
| content | ||
|
|
||
| https://support.crowdin.com/cli-tool/ | ||
| </TabItem> | ||
| </Tabs> | ||
| ```` | ||
|
|
||
| - Setup environment variable: | ||
| ````` | ||
|
|
||
| ``` | ||
| CROWDIN_DOCUSAURUS_API_KEY = XXX | ||
| ``` | ||
| ### Translation | ||
|
|
||
| - Upload: | ||
| [Crowdin](https://crowdin.com/project/casbin-website) and [Docusaurus i18n](https://docusaurus.io/docs/i18n/introduction) is used for Casbin website's translation. | ||
|
|
||
| ``` | ||
| crowdin --config ../crowdin.yaml upload sources --auto-update -b master | ||
| ``` | ||
| Note: Please do not translate strings like `:::note`, `:::tip`, wrong translation may cause typographical error([casdoor-website#305](https://github.com/casdoor/casdoor-website/issues/305)). | ||
|
|
||
| - Download: | ||
| ### Website Development | ||
|
|
||
| ``` | ||
| crowdin --config ../crowdin.yaml download -b master | ||
| ``` | ||
| See [Creating Pages](https://docusaurus.io/docs/creating-pages) to learn how to create a page. | ||
|
|
||
| > Noting that the translation of the official website will update after a Pull Request is merged | ||
| See [Styling and Layout](https://docusaurus.io/docs/styling-layout) to learn how to modify styles. | ||
|
|
||
| ## License | ||
| See [Swizzling](https://docusaurus.io/docs/swizzling) to learn how to modify Docusaurus built-in components. | ||
|
|
||
| Casbin is [Apache licensed](./LICENSE). | ||
| ## LICENSE | ||
|
|
||
| Casbin documentation is [Creative Commons licensed](./LICENSE-docs). | ||
| [Apache-2.0 license](./LICENSE). |