This repository contains the raw source files for the documentation of the Umbraco eCommerce platform Tea Commerce. The live version of these docs can be found at https://docs.teacommerce.net.
If you would like to help improve our documentation, contributions via pull request are our prefered method. I guide for which follows:
All contributions / contributors are expected to abide by our Code of Conduct
- Yarn - Yarn is our prefered package installer so contributors should make sure Yarn has been installed globally on your machine
- Fork this repository on GitHub.
- Clone your forked repository (not our original one) to your hard drive with git clone https://github.com/YOURUSERNAME/tea-commerce-documentation.git
- Open the
tea-commerce-documentationdirectory - Open a command window and start a local instance of the site via:
yarn install
yarn docs:dev- Launch http://localhost:8080 in a browser to view the site
- Create a branch in your local repository
- Make the changes you'd like to submit
- Commit you changes locally
- Push your changes to your GitHub repository
- Submit your changes as a Pull Request to our GitHub repository
NB A Pull Request should only contain changes for a single "logical group" of changes. If you have multiple changes to make, you should create branches / Pull Request for each set of changes.
When writing documentation there are a number of principles that should be followed. These principles are documented below.
The Tea Commerce documentation site is powered by Vuepress, a vuejs static site generator. You should read up on the basics of Vuepress to get an understanding of the available features.
Documentation files are written using markdown. If you need something more complex than is possible with markdown, you can write bespoke HTML instead, however, you should aim to write as much as you can in the markdown format.
For details on the various supported markdown tags, checkout the Vuepress documentation.
As well as the built in markdown tags, there are number of custom markdown tags available.
Tabs allow you to show content in a tabbed interface. To create tabs you can use the following markdown syntax
:::: tabs
::: tab "Tab Name"
Tab content goes here
:::
::::
If your documentation requires an image or static file to link to, these files should be placed in the docs/.vuepress/public folder / sub folder. Anything in this folder will be copied to the site root on compilation. To reference the files in your markdown, you can do so using an absolute path assuming the files have been copied to the root folder.
For example, if you place a file myimage.png into the docs/.vuepress/public/img folder, you can reference this image in your markdown using the path /img/myimage.png.
If you need to create a new page, rather than creating a file with the page name, you should instead create a directory with the desired page name and inside it create a README.md file in which to add the page contents.
We do this to ensure all URL's are extentionless.
If you need to create any custom CSS styles, these should be added to the docs/.vuepress/styles.styl file. This file is written using stylus syntax, however you can write regular CSS if you prefer.
As we are using Vupress, you can also create custom Vue components should you need to add some new functionality. Components should be placed in the docs/.vuepress/components directory. And files in this directory will be regisered globally and can be used directly in your markdown files.
You should check beforhand before creating any custom components to ensure the new behaviour is desired.
This repository contains documentation for multiple versions of Tea Commerce. Versioned docs are located in numbered directories inside the docs folder. When making changes, you should ensure you are updating the correct version before you commit your changes.
If your changes affect multiple versions of Tea Commerce, you should update the files in each version the change is required in.
Contributors shouldn't need to create new versions of the documentation, but if you do, to create a new version you should duplicate the current version folder, changing it's name to the new version number, and then update the docs/.vuepress/versions.json file to update the current, next and previous version numbers accordingly.
This project is licensed under the terms of the MIT license.