diff --git a/README.md b/README.md index c30f6061..5d387f59 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,15 @@ For more information of the configuration, see the reference in Flex Docs. **Note:** If you want to build your own Flex marketplace on top of the template, you should fork the -repository instead of cloning it. See the [Customization guide](./docs/customization-guide.md). +repository instead of cloning it. See the +[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex +Docs. ## Getting started with your own customization If you want to build your own Flex marketplace by customizing the template application, see the -[Customization guide](docs/customization-guide.md) documentation. +[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex +Docs. ## Deploying to Heroku @@ -48,7 +51,12 @@ for more information. ## Documentation -Full documentation can be found in the [docs directory](docs/). +We are currently moving documentation to the Flex Docs site, so at the moment part of the +documentation is in this repository and part is in the Flex Docs site. + +See the Flex Docs site: https://www.sharetribe.com/docs/ + +Rest of the documentation can be found in the [docs directory](docs/). ## License diff --git a/docs/README.md b/docs/README.md index 0ff28abd..6cc2586b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,17 +41,21 @@ Docs: - [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/) tutorial. -## How to customize this template +## Customization guide The easiest way to start a customization project is to read through the -[customization guide](customization-guide.md). After that, you probably should start with changing +[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex +Docs. + +## How to customize this template + +After going through the customization guide, you probably should start with changing [translations](translations.md), [common styles](styling.md) in marketplace.css, and then create [static pages](static-pages.md) and modify [Terms of Service and Privacy Policy pages](terms-of-service-and-privacy-policy.md). Documentation for specific topics can be found in the following files: -- [Customization guide](customization-guide.md) - [Folder structure](folder-structure.md) - [Translations](translations.md) - [Styling a marketplace](styling.md) @@ -65,7 +69,6 @@ Documentation for specific topics can be found in the following files: Docs - [Extend the listing data model](extend-listing.md) - [Search filters](search-filters.md) -- [Testing](testing.md) - [Continuous Integration (CI)](ci.md) - [Original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md) - [Customization checklist](customization-checklist.md) @@ -76,6 +79,7 @@ Documentation for specific topics can be found in the following files: See also the following articles in the [Flex Docs](https://www.sharetribe.com/docs/) website: - [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/) +- [How to test FTW](https://www.sharetribe.com/docs/guides/how-to-test-ftw/) - [How to set up Sentry to log errors in FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-sentry-to-log-errors-in-ftw/) - [How to set up Analytics for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/) - [How to set up Content Security Policy (CSP) for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-csp-for-ftw/) diff --git a/docs/customization-guide.md b/docs/customization-guide.md index 8793669a..4d79c6b1 100644 --- a/docs/customization-guide.md +++ b/docs/customization-guide.md @@ -1,159 +1,5 @@ # Customization guide -So you've decided to build your own Flex marketplace using the template. That's awesome! This guide -will help you in setting up your fork and describes the general workflow. +Documentation moved to the Flex Docs site: -**Note:** If you cloned the repository like described in the Quick start section of the project -README file, you probably don't want to make the customizations in that project. Forking the -repository is the recommended way to proceed. Follow this guide for instructions. - -## Getting started - -We recommend going through the -[Getting started articles](https://www.sharetribe.com/docs/background/getting-started/) in the Flex -Docs: - -- [Introducing Flex](https://www.sharetribe.com/docs/background/introducing-flex/) -- [What development skills are needed?](https://www.sharetribe.com/docs/background/development-skills/) -- [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/) - tutorial. - -## Requirements - -Install required tools: - -- [Node.js](https://nodejs.org/) -- [Yarn](https://yarnpkg.com/) - -## Technologies - -Depending on what you want to change in the template, various skills help in achieving your goal. -Some of the basic customizations don't require specific coding skills, but many customisations -become technically involved. We've tried to keep the technology setup as simple as possible, and -frontend developers with experience in widely used tooling should feel comfortable right from the -get-go. - -Here are some main technologies that the template uses: - -- JavaScript: programming language for the whole application -- CSS: styling the user interface using [CSS Modules](https://github.com/css-modules/css-modules) -- [React](https://reactjs.org/): library for creating user interfaces with components -- [Redux](https://redux.js.org/): state and data flow handling -- [Final Form](https://github.com/final-form/final-form): forms -- [React Router](https://reacttraining.com/react-router/): routing -- [Express](https://expressjs.com/): server - -## Setup - -To start a new customization project, you should create a separate Git repository and setup the Git -remotes so that you can pull in changes from the main (upstream) repository to your custom -repository. - -### Fork the repository - -See the [Fork a repo](https://help.github.com/articles/fork-a-repo/) documentation for instructions -for forking a repository in GitHub. - -In the directory you want to create the project in: - - git clone git@github.com:YOUR_USERNAME/YOUR_FORK.git # clone your fork - cd YOUR_FORK # changed to the cloned directory - git remote add upstream git@github.com:sharetribe/flex-template-web.git # add the template as the upstream remote - -See also the -[Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/) -documentation. - -### Pull in latest upstream changes - -If you want to update your local customization project with changes in the template, you should pull -in changes from the upstream remote. - -**Note:** Depending on the changes you've made to the template, this might be hard/impossible -depending on what has changed in the template. You should mainly think of the template being the -starting point of your customization, not something that is constantly updated. - -In the `master` branch (or in the branch you want to merge in the upstream changes): - -1. Fetch the latest changes from the upstream repository: - - ```sh - git fetch upstream - ``` - -1. Merge the changes to your local branch - - ```sh - git merge upstream/master - ``` - -1. Fix possible merge conflicts, commit, and push/deploy. - -See also the [Syncing a fork](https://help.github.com/articles/syncing-a-fork/) documentation. - -## Installing dependecies - -In your project root, install dependencies: - - yarn install - -## Configuration - -There are some mandatory configuration, and some configuration that you most likely want to at least -go through. - -To get started, run: - - yarn run config - -This command will create `.env` file and guide you trough setting up the required environment -variables. The `.env` file is the place to add your local configuration. It is ignored in Git, so -you'll have to add the corresponding configuration also to your server environment. - -There are some mandatory configuration variables that are defined in the template. See the Flex Docs -[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/) -reference for more information. - -See also the [src/config.js](../src/config.js) file for more configuration options. - -## Development - -To develop the application and to see changes live, start the frontend development server: - - yarn run dev - -**Known issues:** - -- Adding/changing `import`s may not be synced properly with ESLint. You may see an error - `Unable to resolve path to module` even though the module existing in right path. Restarting the - server doesn't help. To solve the issue, you need to make a change to the file where the error - occurs. - -## Development Server - -The usual way to develop the application is to use the frontend development server (see above). -However, in production you likely want to use the server rendering setup. To develop the server -rendering setup locally, run: - - yarn run dev-server - -This runs the frontend production build and starts the Express.js server in `server/index.js` that -renders the application routes in the server. The server is automatically restarted when there are -changes in the `server/` directory. - -**Note:** this server does **not** pick up changes in the frontend application code. For that you -need to build the client bundle by restarting the server manually. - -## Tests - -To start the test watcher, run - - yarn test - -See more in the [testing documentation](testing.md). - -## Customization - -There are many things that you should change in the default template, and many more that you can -change. Read [more about FTW](README.md) and check the -[Customization checklist](customization-checklist.md) documentation too before publishing your site. +https://www.sharetribe.com/docs/guides/how-to-customize-ftw/ diff --git a/docs/deploying-to-production.md b/docs/deploying-to-production.md index 9bea518c..d28b4429 100644 --- a/docs/deploying-to-production.md +++ b/docs/deploying-to-production.md @@ -73,8 +73,9 @@ changes to environment variables. If you haven't done this already, you just need to click the "Fork" button on the top-right corner of the page: -Read more from [Customization guide](./customization-guide.md#fork-the-repository) for more -instructions. +For more information, see the +[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex +Docs. ### Creating a new app diff --git a/docs/testing.md b/docs/testing.md index b9eefcd7..1f7cf274 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,30 +1,5 @@ -# Testing Flex template for the web +# Testing Flex Template for Web -The test setup is based on the `create-react-app` test setup and is using the -[Jest testing framework](https://facebook.github.io/jest/). See the -[Testing Components](create-react-app.md#testing-components) and -[Experimental Snapshot Testing](create-react-app.md#experimental-snapshot-testing) sections in the -`create-react-app` documentation. +Documentation moved to the Flex Docs site: -## Running tests - -To start the test watcher that automatically updates when files change, run - - yarn test - -If you want to run the tests once and not start the watcher, run - - CI=true yarn test - -Note that this also runs the linter. - -## Jest - -To learn more about testing with Jest, read the following documentation: - -- [Getting Started](https://facebook.github.io/jest/docs/getting-started.html) -- [Tutorial - React](https://facebook.github.io/jest/docs/tutorial-react.html) -- [Tutorial - Async](https://facebook.github.io/jest/docs/tutorial-async.html) -- [Snapshot Testing](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html) blog post -- [API Reference](https://facebook.github.io/jest/docs/api.html) lists the global environment with - the available functions and the assertion matchers +https://www.sharetribe.com/docs/guides/how-to-test-ftw/