Skip to content

Commit d63ad0f

Browse files
peterjaappeterjaap
committed
Update more docs
1 parent df36efb commit d63ad0f

File tree

7 files changed

+269
-13
lines changed

7 files changed

+269
-13
lines changed

‎docs/basics/configuration.md‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -147,15 +147,3 @@ Head over to the admin of your Magento installation.
147147
* Product Attributes
148148
*Attributes to make available in Prismic Integration Fields. The following attributes will always be made available: name, image, status, short_description, updated_at.*
149149
* Sitemap section
150-
151-
### Optionally, protect with a key
152-
153-
### Content types
154-
155-
### Fetch Links
156-
157-
### Debugging
158-
159-
### Preview mode
160-
161-
### Multi repo

‎docs/basics/multi-repo.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Multiple Repositories
3+
description: Working with multiple Prismic repositories in Magento 2
4+
---
5+
6+
# Multiple Repositories
7+
8+
The module supports working with multiple Prismic repositories, allowing different stores or themes to use different content repositories.
9+
10+
## Configuration
11+
12+
### Enabling Multi-repo Support
13+
14+
1. Go to Stores > Configuration > Elgentos > Prismic.IO
15+
2. Navigate to Multi Repository section
16+
3. Set "Enable Multiple Repositories" to "Yes"
17+
4. Configure the "Repository Field" setting
18+
19+
### Repository Field
20+
21+
The repository field determines which Prismic field contains the repository information:
22+
23+
```json
24+
{
25+
"Main": {
26+
"repository": {
27+
"type": "Text",
28+
"config": {
29+
"label": "Repository"
30+
}
31+
}
32+
}
33+
}
34+
```
35+
36+
## Implementation
37+
38+
### Store-specific Repositories
39+
40+
Each store view can connect to a different Prismic repository:
41+
42+
1. Switch to specific store view in admin
43+
2. Configure Prismic API endpoint for that store
44+
3. Set appropriate API token
45+
46+
### Cache Considerations
47+
48+
When using multiple repositories:
49+
50+
1. **Cache Flush Settings**
51+
```xml
52+
<prismicio>
53+
<cache_flush>
54+
<content_types>page,blog_post</content_types>
55+
</cache_flush>
56+
</prismicio>
57+
```
58+
59+
2. **Cache Tags**
60+
- Each repository gets unique cache tags
61+
- Content types are prefixed with repository ID
62+
- Cache is cleared per repository
63+
64+
## Best Practices
65+
66+
1. **Repository Organization**
67+
- Use consistent content types across repos
68+
- Document repository purposes
69+
- Consider content sharing needs
70+
71+
2. **Performance**
72+
- Monitor API usage per repository
73+
- Configure appropriate cache settings
74+
- Consider CDN implementation
75+
76+
3. **Maintenance**
77+
- Keep repositories synchronized
78+
- Document repository relationships
79+
- Plan for content migrations
80+
81+
## Troubleshooting
82+
83+
1. **Repository Connection**
84+
- Verify API endpoints
85+
- Check access tokens
86+
- Confirm store assignments
87+
88+
2. **Cache Issues**
89+
- Review cache configuration
90+
- Check cache tags
91+
- Monitor cache storage
92+
93+
3. **Content Sync**
94+
- Validate webhook setup
95+
- Check repository field values
96+
- Review store-specific settings

‎docs/basics/routes-admin.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Routes Management
3+
description: Managing Prismic routes in the Magento admin interface
4+
---
5+
6+
# Routes Management
7+
8+
The module provides an admin interface for managing Prismic routes under Content > PrismicIO > Routes.
9+
10+
## Accessing Routes
11+
12+
1. Log into your Magento admin panel
13+
2. Navigate to Content > PrismicIO > Routes
14+
3. Here you can view and manage all Prismic routes
15+
16+
## Managing Routes
17+
18+
### Creating a Route
19+
20+
1. Click "Add New Route"
21+
2. Fill in the required fields:
22+
- Title: For admin reference
23+
- Content Type: The Prismic content type (e.g., blog_post)
24+
- Route: The URL path (must start with /, e.g., /blog)
25+
- Store View: Select which store views this route applies to
26+
27+
### Editing Routes
28+
29+
1. Find the route in the grid
30+
2. Click "Edit" in the Action column
31+
3. Modify the route settings
32+
4. Click "Save Route"
33+
34+
### Route Settings
35+
36+
- **Title**: Internal reference name
37+
- **Content Type**: Matches your Prismic custom type
38+
- **Route**: URL path pattern
39+
- **Store Views**: Which stores show this content
40+
- **Status**: Enable/disable the route
41+
42+
## URL Structure
43+
44+
Routes define how Prismic content is accessed on your store:
45+
46+
```
47+
/{route}/{uid}
48+
Example: /blog/summer-fashion-trends
49+
```
50+
51+
## Best Practices
52+
53+
1. **URL Structure**
54+
- Use clear, descriptive paths
55+
- Keep URLs SEO-friendly
56+
- Consider multi-store impacts
57+
58+
2. **Content Types**
59+
- Match Prismic custom types exactly
60+
- One route per content type per store
61+
- Consider language variations
62+
63+
3. **Store Views**
64+
- Assign routes appropriately
65+
- Consider URL conflicts
66+
- Plan for translations
67+
68+
## Troubleshooting
69+
70+
1. **404 Errors**
71+
- Verify route is enabled
72+
- Check store view assignment
73+
- Confirm content type exists
74+
75+
2. **URL Conflicts**
76+
- Check for duplicate routes
77+
- Review store view assignments
78+
- Verify URL patterns
79+
80+
3. **Content Not Showing**
81+
- Validate content type name
82+
- Check store view settings
83+
- Review route status

‎docs/basics/webhooks.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Webhooks and Debug Settings
3+
description: Configuring webhooks and debug options for the Prismic Magento 2 integration
4+
---
5+
6+
# Webhooks and Debug Settings
7+
8+
The module provides webhook support for content updates and debug options for development.
9+
10+
## Webhook Configuration
11+
12+
### Setting Up Webhooks
13+
14+
1. Go to Stores > Configuration > Elgentos > Prismic.IO
15+
2. Navigate to Webhook Settings
16+
3. Configure the webhook secret
17+
18+
### In Prismic
19+
20+
1. Go to your Prismic repository settings
21+
2. Navigate to Webhooks
22+
3. Add a new webhook:
23+
```
24+
URL: https://your-store.com/prismicio/webhook
25+
Secret: [Your configured secret]
26+
```
27+
28+
### Webhook Events
29+
30+
The webhook handles:
31+
- Content publication
32+
- Content deletion
33+
- Content updates
34+
- URL rewrite generation
35+
- Cache invalidation

‎docs/best-practices.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Best Practices
2+
3+
1. **Webhook Security**
4+
- Use strong secrets
5+
- Validate webhook sources
6+
- Monitor webhook logs
7+
8+
2. **Debug Settings**
9+
- Disable in production
10+
- Use for development only
11+
- Monitor error logs
12+
13+
3. **Performance Impact**
14+
- Consider logging overhead
15+
- Monitor webhook processing
16+
- Cache appropriately
17+
18+
## Troubleshooting
19+
20+
1. **Webhook Issues**
21+
- Verify secret configuration
22+
- Check webhook logs
23+
- Monitor response codes
24+
25+
2. **Debug Problems**
26+
- Review permission settings
27+
- Check log configuration
28+
- Verify store settings

‎docs/layout/debug.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,27 @@ To enable debug mode:
3131
3. Under the Content section, enable "Debugging"
3232
4. Clear the cache
3333

34-
When debug mode is enabled, you'll see additional information in your browser's developer tools and on the page if the debug block is present.
34+
When debug mode is enabled, you'll see additional information in your browser's developer tools and on the page if the debug block is present.
35+
36+
## Debug Mode Features
37+
38+
When debug is enabled:
39+
- Detailed error messages
40+
- API request logging
41+
- Template path information
42+
- Context debugging tools
43+
44+
## Debug Output
45+
46+
Add the debug parameter to see detailed information:
47+
```
48+
?prismicio_debug=1
49+
```
50+
51+
## Exception Handling
52+
53+
With exceptions enabled:
54+
- Detailed stack traces
55+
- API error information
56+
- Context resolution errors
57+
- Template processing issues

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,11 @@ nav:
1313
- Configuration: basics/configuration.md
1414
- Content types: basics/content-types.md
1515
- Routing: basics/routing.md
16+
- Routes: basics/routes.md
17+
- Multi-repo: basics/multi-repo.md
1618
- Document structure: basics/document-structure.md
1719
- Sitemap: basics/sitemap.md
20+
- Webhooks: basics/webhooks.md
1821
- Frontend:
1922
- Layout handles: layout/handles.md
2023
- Debug: layout/debug.md

0 commit comments

Comments
 (0)