further additions to README & CONTRIBUTING

Author: TC-MO

CONTRIBUTING.md

@@ -26,13 +26,64 @@
 3. Run `npm install`
 4. Start development server: `npm start`
 
+This will be enough to work on Platform, Academy and, OpenAPI. If you want to work on entire documentation set you need to join them using Nginx.
+
+#### Join all repositories with Nginx
+
+1. Clone all the repositories
+2. Run `npm start:dev` instead of `npm start` from the main repository
+3. Run `npm start -- --port <number>` to start docusaurus instance on specific port, refer to the table for each repo port
+
+    |Repository|Port|
+    |:---|:---|
+    |apify-docs|3000|
+    |apify-client-js|3001|
+    |apify-client-python|3002|
+    |apify-sdk-js|3003|
+    |apify-sdk-python|3004|
+    |apify-cli|3005|
+
+4. To serve them together, setup the Nginx server with the following config
+
+    ```nginx
+        server {
+    listen       80;
+    server_name  docs.apify.loc;
+    location / {
+        proxy_pass http://localhost:3000;
+    }
+    location /api/client/js {
+        proxy_pass http://localhost:3001;
+    }
+    location /api/client/python {
+        proxy_pass http://localhost:3002;
+    }
+    location /sdk/js {
+        proxy_pass http://localhost:3003;
+    }
+    location /sdk/python {
+        proxy_pass http://localhost:3004;
+    }
+    location /cli {
+        proxy_pass http://localhost:3005;
+    }
+    }
+    ```
+
+5. Add a record to `/etc/hosts`, which maps the `docs.apify.loc` to a localhost:
+
+    ```text
+    127.0.01 docs.apify.loc
+    ```
+
+You should be able to open https://docs.apify.loc in your browser and run all the repositories jointly as one project.
 ## Style guide
 
 ### Language guidelines
 
 - Use US English
 - Write in inclusive language
-- Avoid directional language (like "left" or "right")
+- Avoid directional language (like "left" or "right" or instead of "see" use "check out")
 - Use active voice whenever possible
 
 ### Formatting conventions
@@ -41,12 +92,13 @@
 
    - use *Bold* for UI elements
    - use **Italics** for emphasis
-   - use `code` for inline code
+   - use `code` for inline code, by using back-ticks (\`\`\)
    - use code blocks with language specification
+   - usd [code tabs](https://docusaurus.io/docs/markdown-features/tabs) whenever you want to include examples of implementation in more than one language
 
 2. Documentation elements:
 
-    - Use admonitions
+    - Use [admonitions](https://docusaurus.io/docs/2.x/markdown-features/admonitions) to emphasize cruciac information, available admonitions are:
       - note
       - tip
       - info
@@ -55,15 +107,25 @@
     - Implement code tabs for multiple languages
     - Include proper metadata in front matter
 
+    Example of proper usage and formatting:
+
+    ```text
+    :::note Your Title Here
+
+    Your important message here.
+
+    :::
+    ```
+
 3. Screenshots:
 
     - Use light theme when taking screenshots
     - Include meaningful alt texts
     - Use red indicators
 
-### Metadata best practices
+### Front matter metadata best practices
 
-- Keep descriptions between 140-160 characters
+- Keep descriptions between 140 and 160 characters
 - Avoid repetitive keywords
 - Use action-oriented phrasing
 - Exclude the word "documentation" in descriptions
@@ -110,7 +172,7 @@ The API reference documentation at docs.apify.com is built directly froum our Op
 1. Navigate to `apify-api/openapi/components/schemas`
 2. Create a new file named after your schema
 3. Define the schema structure
-4. Reference schea using `$ref` in other files
+4. Reference schema using `$ref` in other files
 
 Example schema
 
@@ -127,11 +189,11 @@ properties:
 #### Path documentation
 
 1. Navigate to `apify-api/openapi/paths`
-2. Create YAML file following the URL structure
+2. Create YAML file following the URL structure replacing `/` with `@`
 3. Place path parameters in curly braces (e.g., {queueId})
 4. Add path reference to openapi.yaml
 
-Example path structure:
+Example addition to `openapi.yaml` file:
 
 ```yaml
 '/requests-queues':
@@ -140,6 +202,26 @@ Example path structure:
   $ref: './paths/request-queues/request-queues@{queueId}.yaml'
 ```
 
+Example YAML file `request-queues@{queueId}.yaml` in the `paths/request-queues` folder :
+
+```yaml
+get:
+    tags:
+        - Request Queues
+    summary: Get a Request Queue
+    operationId: requestQueues_get
+    description: |
+        You can have a markdown description here.
+    parameters:
+    responses:
+        '200':
+        '401':
+    x-code-samples:
+        -   lang: PHP
+            source:
+                $ref: ../code_samples/PHP/customers/get.php
+```
+
 #### Operation ID conventions
 
 Operation IDs must follow this format:
@@ -156,6 +238,14 @@ Examples:
 - `/requests-queues/{queueId}` PUT -> `requestQueue_put`
 - `/acts/{actorId}/runs` POST -> `act_runs_post`
 
+#### Code samples
+
+1. Navigate to the `openapi/code_samples` folder
+2. Navigate to the `<language>` sub-folder
+3. Navigate to the `path` folder, and add ref to the code sample
+
+Add languages by adding new folders at the appropriate path level.
+
 #### Submitting changes
 
 1. Make your changes following the guidelines above

README.md

@@ -4,11 +4,14 @@
 
 ## Overview
 
-This repository is the home of Apify's documentation, available at [docs.apify.com](https://docs.apify.com/). The documentation uses [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
+This repository is the home of Apify's documentation, available at [docs.apify.com](https://docs.apify.com/). The documentation uses [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) & [Docusaurus](https://docusaurus.io/).
 
-### Documentation structure
+## Documentation structure
+
+Our documentation ecosystem consists of:
 
 - **Platform documentation**: Located in the [/sources](https://github.com/apify/apify-docs/tree/master/sources) directory
+- **Academy**: Platform-independent courses on scraping technique. Located in the [/sources](https://github.com/apify/apify-docs/tree/master/sources) directory
 - **API documentation**:
   - **OpenAPI documentation**: [OpenAPI reference](https://docs.apify.com/api/v2)
   - [JavaScript/Node.js](https://docs.apify.com/api/client/js/)
@@ -29,11 +32,11 @@ Before contributing, read these essential resources:
 
 Our documentation consists of these main sections:
 
-1. **Academy**: Platform-independent courses on scraping techniques
-2. **Platform**: Main documentation for using Apify as a product
-3. **API**: API reference and client libraries documentation
-4. **SDK**: SDK libraries documentation
-5. **CLI**: Documentation for building code and platform interaction
+1. **Academy**: Collection of mostly platform-independent courses on scraping techniques.
+2. **Platform**: Main documentation for using Apify as a product.
+3. **API**: API reference and client libraries documentation.
+4. **SDK**: SDK libraries documentation.
+5. **CLI**: Documentation for building code and platform interaction.
 
 ### Source Repositories
 
@@ -44,13 +47,14 @@ Our documentation consists of these main sections:
 - apify-sdk-python
 - apify-cli
 
-### Homepage structure
+## Architecture
 
-The homepage menu cards (in `docs/homepage_content.json`) serve three user categories:
+Our documentation is built using:
 
-1. **Beginners**: Get started, Use Actors and scrapers
-2. **Experienced Users**: Reduce blocking, Use platform features
-3. **Advanced Users**: Build Actors, Advanced tutorials and debugging
+- **Docusaurus**: Powers our documentation platform
+- **Shared Theme**: Custom `@apify/docs-theme` package
+- **Automated Deployment**: CI/CD pipeline for continuous updates
+- **Nginx routing**: Handles subdomain routing and redirects
 
 ## Need help