Pelican "Could not process" reStructuredText in CI

By Daniel Zoghalchali·Latchkey

Pelican renders reStructuredText with docutils. A malformed directive, an unknown role, or a severe markup error makes docutils fail, and Pelican logs "Could not process" for that file and aborts on errors.

What this error means

pelican prints "Could not process content/X.rst" with a docutils message such as "Unknown directive type" or "Severe error", and the build fails (especially with warnings treated as errors).

ERROR: Could not process content/post.rst
  Unknown directive type "code-block".
  CRITICAL: Could not process content/post.rst

Common causes

An unknown directive or role

The article uses a directive (code-block) that needs Pygments or an extension that is not available, so docutils does not recognize it.

Malformed rST markup

Bad indentation under a directive or an unterminated block makes docutils raise a severe error.

How to fix it

Provide the directive's dependency

Install Pygments so code-block and highlighting directives resolve, then rebuild.

pip install Pygments
pelican content -s pelicanconf.py

Fix the rST markup the error names

1. Open the file at the reported error.
2. Correct the directive name and the indentation under it.
3. Re-run pelican to confirm the file processes.

How to prevent it

• Install Pygments for code directives.
• Validate rST locally before committing.
• Keep directive indentation consistent.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation