mirror of
https://github.com/silverstripe/doc.silverstripe.org
synced 2024-10-22 17:05:50 +02:00
a5c81f2c84
* DOC Update and restructure README for clarity and accuracy * NEW Add anchor links to headings
112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
[](https://app.netlify.com/sites/ss-docs/deploys)
|
|
|
|
# doc.silverstripe.org
|
|
|
|
This repository contains the source code powering [the Silverstripe CMS
|
|
developer documentation website](https://docs.silverstripe.org) and
|
|
[userhelp website](https://userhelp.silverstripe.org).
|
|
|
|
This application is build on [Gatsby](https://gatsbyjs.com), a static
|
|
site generator based on [React](https://reactjs.org). It sources content
|
|
from the [framework](https://github.com/silverstripe/silverstripe-framework)
|
|
repository for each major release.
|
|
|
|
**This repository does NOT contain any documentation.**
|
|
|
|
The developer documentation is stored in the framework module
|
|
repository, in the `docs` folder. For example, the documentation for the
|
|
master branch of Silverstripe CMS is stored in
|
|
[https://github.com/silverstripe/silverstripe-framework/tree/master/docs](https://github.com/silverstripe/silverstripe-framework/tree/master/docs).
|
|
|
|
The userhelp documentation is stored in the [userhelp-content repo](https://github.com/silverstripe/silverstripe-userhelp-content/).
|
|
|
|
## Installation
|
|
|
|
To set up a local instance of [doc.silverstripe.org](https://github.com/silverstripe/doc.silverstripe.org):
|
|
|
|
* Clone this repository to an empty directory
|
|
```
|
|
git clone https://github.com/silverstripe/doc.silverstripe.org path/to/ssdocs
|
|
```
|
|
|
|
### Docker install
|
|
|
|
No local NodeJS nor gatsby-cli is required for this option.
|
|
|
|
* Make sure docker and docker-compose are installed and docker daemon is running
|
|
* Simply use `./docker/run` to run gatsby commands
|
|
- `./docker/run build` would be equal to run `gatsby build` within a container
|
|
- `./docker/run develop -p 8000` would run `gatsby develop -p 8000` within a container.
|
|
|
|
### Native install
|
|
|
|
* Install [Gatsby CLI](https://gatsbyjs.com)
|
|
|
|
## Developing
|
|
|
|
Once cloned, from the root of the repository, run the command `yarn dev-docs`
|
|
to instantiate a development server. This will consume all of the markdown files in both major release
|
|
branches and allow you to browse the developer documentation site on `http://localhost:8000` by default
|
|
(see the [Gatsby docs](https://www.gatsbyjs.org/docs/) for instructions on customising the port).
|
|
|
|
## Building
|
|
|
|
To test a static build of the site, first create a production environment file.
|
|
|
|
```
|
|
cp .env.development .env.production
|
|
```
|
|
|
|
Then, run the build.
|
|
|
|
```
|
|
yarn build-docs
|
|
yarn serve
|
|
```
|
|
|
|
These commands will give you an exact representation of how the site will run on a production server, with
|
|
statically generated html files and server-side rendering.
|
|
|
|
## Toggling between docs and userhelp
|
|
|
|
Whether the application uses the `docs.silverstripe.org` content or `userhelp.silverstripe.org` is determined
|
|
by the environment variable, `DOCS_CONTEXT`. You can set this in the `.env.development` file, or use one of
|
|
the script shortcuts:
|
|
|
|
```
|
|
yarn dev-docs
|
|
yarn dev-user
|
|
yarn build-docs
|
|
yarn build-user
|
|
```
|
|
|
|
## Authoring
|
|
|
|
You can make changes directly to the source markdown files and get live updates in the development
|
|
server without having to rebuild the app or even refresh the browser. The clones of the `silverstripe/framework`
|
|
repositories are in the `.cache/gatsby-source-git` folder in the root of this project. There are subfolders
|
|
for `3/` and `4/`, respective to their branch names. You can edit the files in `docs/en` from there.
|
|
|
|
Just don't forget to merge your changes upstream once you're done. Building the gatsby app will not preserve
|
|
your content changes, since the remote repositories are the source of truth.
|
|
|
|
## Deploying content changes
|
|
|
|
Once your contribution has been merged into the master branch, it will be deployed to production via a
|
|
Github action in the repository that holds the markdown files (e.g. `silverstripe/silverstripe-framework` for docs).
|
|
|
|
## Deploying app changes
|
|
|
|
Once your change is merged in to the `master` branch of this repository, it will be deployed to production.
|
|
|
|
## Contribution
|
|
|
|
To contribute an improvement to the https://docs.silverstripe.org or https://userhelp.silverstripe.org functionality or
|
|
theme, submit a pull request on the [GitHub project](https://github.com/silverstripe/doc.silverstripe.org). Any approved pull requests will make
|
|
their way onto the https://docs.silverstripe.org or https://userhelp.silverstripe.org sites in the next release.
|
|
|
|
If you wish to edit the documentation content, submit a pull request
|
|
on the
|
|
[framework Github project](https://github.com/silverstripe/silverstripe-framework) or the
|
|
[userhelp documentation](https://github.com/silverstripe/silverstripe-userhelp-content) repository
|
|
or corresponding module. |