Update filters documentation #198
Conversation
✅ Deploy Preview for open-terms-archive-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
content/terms/explanation/filters.md
Outdated
| - **Be specific**: Target only the noise you want to remove. Avoid broad selectors that might accidentally remove important content. | ||
| - **Be safe**: Ensure your filter doesn't accidentally remove important content. Always check that the generated version still contains the whole terms content. | ||
| - **Be idempotent**: Your filter should produce the same result even if run multiple times on its own output. This ensures consistency and prevents unexpected behavior. | ||
| - **Be efficient**: Use efficient DOM queries and avoid unnecessary operations. Process only the elements you need to modify. |
There was a problem hiding this comment.
It's not blocking, but examples would help to make it more concrete.
content/terms/explanation/filters.md
Outdated
| - **Be idempotent**: Your filter should produce the same result even if run multiple times on its own output. This ensures consistency and prevents unexpected behavior. | ||
| - **Be efficient**: Use efficient DOM queries and avoid unnecessary operations. Process only the elements you need to modify. | ||
|
|
||
| ## When to use filters |
There was a problem hiding this comment.
Why and When sections seems to be a little bit similar. I wonder if it could be grouped together.
| - An existing terms declaration file | ||
| - Identified the noise you want to remove and ensure it cannot be removed with CSS selectors with the [`remove`]({{< relref "terms/reference/declaration/#ref-remove" >}}) property. | ||
|
|
||
| ## Step 1: Check for built-in filters |
There was a problem hiding this comment.
I think I'll use a structure based on the principle that we most often use a built-in filter and optionally a custom filter, so I would put everything related to creating a custom filter on a dedicated how-to page.
There was a problem hiding this comment.
I think we currently do not have enough builtin filters to justify splitting into two pages
| ## Prerequisites | ||
|
|
||
| - An existing terms declaration file | ||
| - Identified the noise you want to remove and ensure it cannot be removed with CSS selectors with the [`remove`]({{< relref "terms/reference/declaration/#ref-remove" >}}) property. |
There was a problem hiding this comment.
I will give an example of noise that will be filtered by removeQueryParams, the only built-in filter available at the moment.
There was a problem hiding this comment.
It's not a tutorial, it's an how to guide, so the idea is not to learn but to apply concrete solution to a real word problem, so I'm not sure it is appropriate
| - **in-place**: they modify the document structure and content directly; | ||
| - **idempotent**: they return the same document structure and content even if run repeatedly on their own result. |
There was a problem hiding this comment.
That sounds like explanations.
content/terms/reference/filters.md
Outdated
|
|
||
| ```js | ||
| export [async] function filterName(document, documentDeclaration) | ||
| export [async] function filterName(document, [parameters]) |
There was a problem hiding this comment.
It's not filterName(document, parameters, documentDeclaration) as it is written in the How to apply filters ?
Co-authored-by: Clément Biron <[email protected]>
No description provided.