This documentation is available at http://docs.geteventstore.com. The website is hosted using GitHub Pages from the gh-pages
branch of this repository. Pages are built with Jekyll using the Redcarpet complier.
What follows is documentation for how to use the Event Store documentation. If you’re planning to make updates or contributions then read on. Otherwise, head on over to the website.
The Event Store documentation is available for many versions of Event Store and its APIs. By default the website shows documentation for the latest stable release of each component. Current sections and versions are:
Section | Versions |
---|---|
Introduction | Always shows latest |
Server | 4.0.0 (latest), 3.3.0, 3.2.0, 3.1.0, 3.0.5, 3.0.3, 3.0.2, 3.0.1, 3.0.0 |
.NET API | 4.0.0 (latest), 3.2.0, 3.1.0, 3.0.2, 3.0.1, 3.0.0 |
HTTP API | 4.0.0 (latest), 3.2.0, 3.1.0, 3.0.3, 3.0.2, 3.0.1, 3.0.0 |
Projections | 4.0.0 (latest) |
The Event Store server uses semantic versioning. API versions are based on the major server version they support.
GitHub Pages renders this documentation using Jekyll. You can generate the site locally and test your changes. Follow the instructions here to get Ruby and Bundler installed.
Once installed, navigate to the root of the repository and run
bundle install
followed by
bundle exec jekyll serve
The compiled site builds into /_site
and is hosted at http://localhost:4000
.
- Make changes (fix typos or grammar, improve wording etc).
- Check to see if older versions need updating too.
- Send a pull request!
- Create new pages and/or sections. Follow the Conventions below.
- If you create a new section add an entry for it to the
top_level_sections
list in_config.yml
. This list determines the order of sections in the navigation sidebar. - Add any new sections to the table at the top of this README.
- Send a pull request!
-
Duplicate the section’s latest version directory and rename it. For example, copy
/server/3.0.0/
to/server/3.0.1/
.Pre-release documentation should have
-pre
after the version number, e.g./server/3.0.1-pre/
. Pre-release documentation will show up on the website but won’t be the default version. In pages’ front matter useversion: "3.0.1 (pre-release)"
. -
Update front matter in all
.md
files in the new directory to use the new version number. -
Make edits to files in the new version as appropriate. You may create or delete pages as necessary.
-
Update the version table at the top of this README.
-
Send a pull request!
- File and directory names are all lowercase.
- Replace spaces with dashes.
- Markdown files take the
.md
extension.
For example:
/dotnet-api/3.0.0/writing-to-a-stream.md
For example:
http://docs.geteventstore.com/dotnet-api/3.0.0/writing-to-a-stream/index.html
Every page written for Jekyll in markdown has front matter. This is metadata for the page. We specify a title for the page, the section it belongs to, and the version for that section. Title and section should be title case. The version number should be in the format X.X.X
.
For example:
---
title: "Writing to a Stream"
section: ".NET API"
version: "3.0.0"
---
Lorem ipsum dolor sit amet…
For index.md
pages you should also include pinned: true
.
The content of our documentation has many authors. These formatting guidelines will help maintain a consistent use of language throughout the docs.
- Acronyms and abbreviations should always be set in uppercase (e.g. API, HTTP, JVM)
- Brand names should have correct typesetting (e.g. cURL, Event Store, JavaScript, .NET)
- Example code should not have a line length of more than 80 characters