ossf / wg-best-practices-os-developers

The Best Practices for OSS Developers working group is dedicated to raising awareness and education of secure code best practices for open source developers.
https://openssf.org
Apache License 2.0
707 stars 122 forks source link

Python guide: include code examples using Jekyll #519

Open gkunz opened 3 months ago

gkunz commented 3 months ago

One objective of the Python guide is to provide executable code examples in separate Python scripts. At the same time, the code examples should also be shown in listings in the guide.

Problem: Markdown itself does not allow to include other files, i.e., such as the code examples.

Proposal: To avoid duplicating the code of the scripts in the markdown files, we can use Jekyll's include_relate primitive [1] to include the scripts in the rendered guide.

Specifically, this pattern seems to work:

```python
{% include_relative compliant01.py %}
```

[1] https://jekyllrb.com/docs/includes/#including-files-relative-to-another-file

cc @myteron @tommcd

myteron commented 2 months ago

Gut feeling tells me that Jekyll appears to me a little to flexible with a potential for injection via variables. Haven't tried. Editing requires to compile and run a web-server. Was somewhat hoping for a more simplistic solution.

gkunz commented 2 months ago

Jekyll is run under the hood by GitHub when rendering the current guides.

I run a test using my fork: