From e28beb5b45d2cd59464b09f655a14cfd370ff7d8 Mon Sep 17 00:00:00 2001 From: Aayushman Singh Date: Fri, 1 Nov 2024 10:25:32 +0530 Subject: [PATCH] Docs - Writing guidelines - Add code example considerations Start a small section to offer some guidance to ensure that code examples are secure, accessible and easier to use. --- docs/contributing/documentation_guidelines.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/contributing/documentation_guidelines.md b/docs/contributing/documentation_guidelines.md index b6c2dac5e1..799a74daa1 100644 --- a/docs/contributing/documentation_guidelines.md +++ b/docs/contributing/documentation_guidelines.md @@ -431,3 +431,29 @@ If you want to use a specific Sphinx directive, consult with core contributors t ### Arbitrary HTML While our documentation tooling offers some support for embedding arbitrary HTML, this is frowned upon. Only do so if there is a necessity, and if the formatting is unlikely to need updates. + +(documentation_code_example_considerations)= + +## Code example considerations + +When including code examples, particularly JavaScript or embedded HTML, it's important to follow best practices for security, accessibility and approaches that make it easier to understand the example. + +These are not hard rules but rather considerations to make when writing example code. + +### Reference example filename + +At the start of a code snippet, it can be helpful to reference an example filename at the top. E.g. `# wagtail_hooks.py` or `// js/my-custom.js`. + +### CSP (Content Security Policy) compliance + +When adding JavaScript from external sources or custom scripts, ensure CSP compliance to prevent security vulnerabilities like cross-site scripting (XSS). + +Avoid `mark_safe` where possible, and use `format_html` and use examples that load external files to manage scripts securely instead of inline `