Consolidate Readme and contributing files (#175)

Author: benitav

CONTRIBUTING.md

@@ -1,25 +1,47 @@
 # Contributing to PowerSync Docs
 
-Thanks for contributing to our documentation! 
+Thanks for contributing to our documentation!
 
 ## License & Contributor License Agreement (CLA)
 
 The PowerSync docs, like [the Service](https://github.com/powersync-ja/powersync-service), are licensed under the Functional Source License (FSL). To contribute, you must accept our Contributor License Agreement (CLA). This is an automated process that occurs when you submit your first pull request (PR).
 
 ## How to Contribute
 
-### From docs.powersync.com directly (recommended)
-TODO: flesh out steps once "suggest edits" is enabled
-
-### Manually
-1. Fork and clone the repo: Click "Fork" on GitHub and clone your fork.
-1. Make Changes: Edit or add markdown files in the relevant directory.
-1. Test Locally: See this repo's [README](/README.md) for instructions.
-1. Submit a PR: Push your changes and open a pull request to the `main` branch.
+1. **Fork and clone your repository:**
+   - On GitHub, click "Fork" at the top right of this repository to create your own copy.
+   - Then clone your fork:
+     ```
+     git clone https://github.com/YOUR-USERNAME/powersync-docs.git
+     cd powersync-docs
+     ```
+2. **Install Mintlify CLI:**
+   ```
+   npx mintlify install
+   ```
+3. **Start the local docs server:**
+   ```
+   npx mintlify dev
+   ```
+   (See the [README](/README.md) for more details and troubleshooting.)
+4. **Make your changes:**
+   - Edit or add .mdx files as needed.
+   - See the [Editing Guidelines in the README](/README.md#editing-guidelines).
+5. **Test your changes locally**
+6. **Submit a pull request:**
+   - Push your changes to your fork.
+   - Open a PR to `powersync-ja/powersync-docs:main`.
+   - Sign the CLA when prompted.
+   - Ensure all checks pass (including broken link checks).
+   - Request a review.
+
+## Publishing
+
+Once your PR is approved and merged to `main`, your changes will be automatically published to https://docs.powersync.com.
 
 ## Getting Help
 
-If you have questions or need assistance:
+If you have questions or need help:
 - Join our [Discord server](https://discord.gg/powersync) to ask questions and connect with the community.
 - Open an issue on GitHub if you encounter a problem or have a suggestion.
 

README.md

@@ -28,38 +28,35 @@ Welcome to the PowerSync documentation repository! Our docs are powered by [Mint
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute.
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
-## Publishing Updates
+## Publishing
 
-Any updates merged into the `main` branch are automatically published to https://docs.powersync.com.
+All changes merged to the `main` branch are automatically published to https://docs.powersync.com.
 
-**Publishing workflow:**
-- Create a pull request (PR) to the `main` branch.
-- Ensure all checks pass (including a check for broken links).
-- Request a review.
-- Merge the PR once approved.
 
-## Navigation & Global Settings
+## Editing guidelines
+
+### Navigation & Global Settings
 
 - Navigation and other global settings are defined in `docs.json`. Learn more in [Mintlify's docs](https://mintlify.com/docs/settings/global).
 - If you move or rename a page, add a redirect using the `redirects` property to ensure existing links continue to work.
 
-## Checking for Broken Links
+### Checking for Broken Links
 
 Regularly check for broken links by running:
 ```
 npx mintlify broken-links
 ```
 
-## Whitelisting & Blacklisting Terms (Vale)
+### Whitelisting & Blacklisting Terms (Vale)
 
 To whitelist terms so Mintlify's Vale integration does not flag them as misspelled:
 - Add terms (one per line, case-insensitive) to `.github/vale/config/vocabularies/PowerSync/accept.txt`.
 - To blacklist terms, create a `reject.txt` file in the same folder.
 - For more info, see [Mintlify's docs](https://mintlify.com/docs/settings/ci#vale) and [Vale's docs](https://vale.sh/docs/keys/vocab).
 
-## Icons
+### Icons
 
 FontAwesome icons are supported: https://fontawesome.com/search
 
@@ -75,7 +72,7 @@ We use the following icons for supported backend databases and SDKs:
 - Node.js: `icon="node-js"`
 - .NET: `icon="microsoft"`
 
-## Useful References
+### Useful References
 
 - [Writing content](https://mintlify.com/docs/page)
 - [Available components](https://mintlify.com/docs/content/components/accordions)