This is the repository and issue trackers for Skygear Documentation Site Generator. The guides are in markdown format at skygeario/guides.
git submodule init
git submodule update
npm install
npm start
npm install
npm run build
-
Push to
production
branch to deploy to https://docs.skygear.io -
run the following command on your local dev machine to ensure it pass the CI server's requirement:
npm run lint npm run test npm run spell-check npm run build release
Files in the public/
folder will be deployed. The Webpack build creates the bundled js in this folder.
Please add the following S3 redirection rule on the deployment S3 bucket for legacy purpose
<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>guide/</KeyPrefixEquals>
</Condition>
<Redirect>
<HostName>docs.skygear.io</HostName>
<ReplaceKeyPrefixWith>guides/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
<RoutingRule>
<Condition>
<KeyPrefixEquals>guides/get-started/</KeyPrefixEquals>
</Condition>
<Redirect>
<HostName>docs.skygear.io</HostName>
<ReplaceKeyPrefixWith>guides/intro/quickstart/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
<RoutingRule>
<Condition>
<KeyPrefixEquals>guides/quickstart/</KeyPrefixEquals>
</Condition>
<Redirect>
<HostName>docs.skygear.io</HostName>
<ReplaceKeyPrefixWith>guides/intro/quickstart/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
</RoutingRules>
To allow replacement of all files upon deployment such that the Android SDK API docs are not removed, please set the following S3 IAM policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets"
],
"Resource": "arn:aws:s3:::*"
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource": "arn:aws:s3:::docs.skygear.io"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl",
"s3:GetObject",
"s3:GetObjectAcl",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::docs.skygear.io/*"
},
{
"Sid": "DisallowAllS3ActionsInApiFolder",
"Effect": "Deny",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::docs.skygear.io/android/reference/*",
"arn:aws:s3:::docs.skygear.io/android/plugins/*",
"arn:aws:s3:::docs.skygear.io/android/build/*"
]
}
]
}
The site is built using the react static boilerplate. You can refer to its documentation for how routes are created.
- Markdown parser: markdown-it
- Syntax highlighting: highlight.js
Please refer to utils/markdown-loader.js
for how it is parsed.
guideRoutes.js
defines the list of routes
- it uses markdown-spellcheck
npm run spell-check
- American English spelling is used.
- Exceptions are in the
.spelling
file.
.
├── /components/ # Shared or generic UI components
│ ├── /Button/ # Button component
│ ├── /Layout/ # Website layout component
│ ├── /Link / # Link component to be used instead of <a>
│ └── /... # etc.
├── /core/ # Core framework
│ ├── /history.js # Handles client-side navigation
│ ├── /router.js # Handles routing and data fetching
│ └── /store.js # Application state manager (Redux)
├── /node_modules/ # 3rd-party libraries and utilities
├── /pages/ # React components for web pages
│ ├── /about/ # About page
│ ├── /error/ # Error page
│ ├── /home/ # Home page
│ └── /... # etc.
├── /public/ # Static files such as favicon.ico etc.
│ ├── /dist/ # The folder for compiled output
│ ├── favicon.ico # Application icon to be displayed in bookmarks
│ ├── robots.txt # Instructions for search engine crawlers
│ └── /... # etc.
├── /test/ # Unit and integration tests
├── /utils/ # Utility and helper classes
│── main.js # React application entry point
│── package.json # The list of project dependencies and NPM scripts
│── routes.json # This list of application routes
│── run.js # Build automation script, e.g. `node run build`
└── webpack.config.js # Bundling and optimization settings for Webpack