From c6fbc12cd1bdff5e0f9aa825e1f5d023e0f9be8b Mon Sep 17 00:00:00 2001 From: jordanliu Date: Thu, 6 Aug 2020 12:35:30 -0500 Subject: [PATCH] readme: formatting Signed-off-by: jordanliu --- docs/README.md | 102 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 81 insertions(+), 21 deletions(-) diff --git a/docs/README.md b/docs/README.md index ee0ccc9d..40b665c3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,33 +1,93 @@ -# Website +

+ + CodeRoad Logo + +

+

+CodeRoad VSCode +

-This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator. +

+ + + +

-### Installation +CodeRoad is a VSCode extension that allows you to play interactive coding tutorials in your editor. -``` -$ yarn -``` +![CodeRoad Image](./docs/static/img/tutorial-example.png) -### Local Development +## Why -``` -$ yarn start -``` +Interactive learning is the most effective way to gain new skills and knowledge. CodeRoad aims to help tutorial creators develop and share interactive content with the community. -This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server. +For learners, there are a number of advantages to running tutorials inside VSCode: -### Build +- learn in a real world coding environment +- get rapid feedback on save and helpful error messages +- users own the code, and can build a Git timeline and deploy a portfolio -``` -$ yarn build -``` +## Getting Started -This command generates static content into the `build` directory and can be served using any static contents hosting service. +### Start -### Deployment +To start the extension, inside VSCode: -``` -$ GIT_USER= USE_SSH=true yarn deploy -``` +- open an empty VSCode workspace (an empty folder) +- launch the app from the VSCode command palette: + - select “View” > “Command Palette” from the top panel OR press `cmd/ctrl + shift + P` + - in the command palette, search for and run `CodeRoad:Start` +- a webview should appear on the right side of your editor. Click "Start" -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +### Install + +Install CodeRoad from [this link in the VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=CodeRoad.coderoad). + +- You may need to reload the window (`ctrl/cmd + R`) +- See ["Start"](#start) to get started. + +### Requirements + +- OS: MacOS, Windows, Linux +- VSCode 1.39.2+ +- Node.js 10+ +- Git + +## How CodeRoad Works + +Read more in the docs about [how CodeRoad works](https://coderoad.github.io/docs/how-coderoad-works). + +## Creating Tutorials + +Build and share your own interactive tutorials. + +Learn more about [how tutorials area created](https://coderoad.github.io/docs/build-tutorial). + +## Editing Tutorials + +Tutorials can be edited directly as markdown on Github. + +## Development + +To run the extension locally: + +- copy environmental variables from `/web-app/.env.example` as `/web-app/.env` +- install dependencies with `yarn install-all` +- build the extension with `yarn build` +- open the extension with the vscode extension debugger by pressing F5. In the new window, open CodeRoad. + +To test a packaged build locally: + +- if on Mac, ensure you have [VSCode command line tools](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) installed +- run `yarn package`. It will build the extension and install it locally. +- open a new vscode window and launch the new version of CodeRoad + +## Contributing + +CodeRoad is an ambitious project, we're always looking for contributors :) + +See [CONTRIBUTING.md](./CONTRIBUTING.md). + +## License + +[AGPL v3](./LICENSE.md)