torchbox / torchbox/django-pattern-library

Add general non-pattern markdown docs to pattern library views

Open
#274 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
423
Forks
53
PR merge metrics
No merged PRs in 30d

Description

Describe the solution you'd like

I'd like to be able to add - both within sections, and at the root level - general markdown files as full page documentation that aren't related to a pattern.

For example, I'd like to be able to have a "Introduction" at the top of the root level of the index, where I can put some information about the library and how to use it, etc.

Somewhat related, I'd like to be able to add a documentation page that isn't related to a pattern, and have it show up as a full page markdown - for example, "Notes regarding Page patterns" or other design notes or guidance for groups of patterns in a particular section or sub-section.

I think the way for this to work would just be to have markdown files in the template directory where the patterns go, but without an actual pattern (html) file.
For top-level markdown, this would maybe need to have a configuration entry in PATTERNS to configure a directory to look in for additional markdown pages.

Describe alternatives you've considered

The alternative is either using something like storybook, but that's still a big leap in complexity that I really don't want to make. This feature would significantly extend the usefulness of django-pattern-library for me, before needing to consider things like Storybook.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing how the pattern template directory and PATTERNS configuration feed the library index and section views. Define the handling for markdown files at the root and within sections, then verify that each renders as a full-page documentation view without requiring an HTML pattern.

Written by the indexing model from the issue text.

Assessment

Tech stack
django, python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.