Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow docs-<subkey> directories for non-rendered files #531

Open
1 task
MiguelRodo opened this issue Jun 7, 2024 · 1 comment
Open
1 task

Allow docs-<subkey> directories for non-rendered files #531

MiguelRodo opened this issue Jun 7, 2024 · 1 comment

Comments

@MiguelRodo
Copy link
Collaborator

MiguelRodo commented Jun 7, 2024

To do

  • Allow docs-<subkey> directories for non-rendered files

Initial thoughts

Not sure how this would look... But I usually have to add a data-raw docs sub-directory for, e.g. scrap, scripts, presentations, etc.

The one issue is that docs feels to me like a jargon term, for where we keep like our site (GitHub uses that as its default). So I want to keep the keyword for that, but it's ambiguous (if we open docs up to non-computed artefacts).

Possible options:

`docs`: docs
`docs-raw`: _docs
`docs-render`: docs
`docs-raw`: docs_raw

Gemini discussion

https://g.co/gemini/share/541165fe28d0

@MiguelRodo MiguelRodo changed the title Consider adding a docs directory that isn't for rendered files Allow docs-<subkey> directories for non-rendered files Jun 7, 2024
@MiguelRodo
Copy link
Collaborator Author

MiguelRodo commented Jun 7, 2024

Final decision

The final decision for organizing your documentation within the YAML configuration is as follows:

  1. The docs keyword is reserved exclusively for rendered documentation (e.g., HTML files generated from qmd). This directory path is set to docs (by default; can be changed).
  2. All other types of documentation (Word, PowerPoint, etc.) will be stored in directories with the prefix docs-. For example:
    • docs-source (for original source documents)
    • docs-slides (for presentation slides)
    • docs-reports (for reports)
    • and so on.

This approach provides a clear distinction between generated and non-generated documentation, while offering flexibility to accommodate various document types in a structured manner.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant