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

Organize docs via SUMMARY.md (or other data file) #261

Open
ninjamuffin99 opened this issue Apr 4, 2024 · 0 comments
Open

Organize docs via SUMMARY.md (or other data file) #261

ninjamuffin99 opened this issue Apr 4, 2024 · 0 comments
Labels
documentation (site) relating to the /documentation pages enhancement

Comments

@ninjamuffin99
Copy link
Member

might also be more relavant to be in flixel-docs repo but whateva!

Right now docs are organized by number, which works generally fine. However if you want to insert a doc in between two other docs, instead of appending to the docs list, you would have to rename all the filenames for the docs!

image image

The folders and the markdown files are all organized / sorted by their number in their filename.

I think an alternative solution is something like the mdbook SUMMARY.md

https://rust-lang.github.io/mdBook/format/summary.html

# Summary

[Introduction](README.md)

# User Guide

- [Installation](guide/installation.md)
- [Reading Books](guide/reading.md)
- [Creating a Book](guide/creating.md)

# Reference Guide

- [Command Line Tool](cli/README.md)
    - [init](cli/init.md)
    - [build](cli/build.md)
    - [watch](cli/watch.md)
    - [serve](cli/serve.md)
    - [test](cli/test.md)
    - [clean](cli/clean.md)
    - [completions](cli/completions.md)
- [Format](format/README.md)
    - [SUMMARY.md](format/summary.md)
        - [Draft chapter]()
    - [Configuration](format/configuration/README.md)
        - [General](format/configuration/general.md)
        - [Preprocessors](format/configuration/preprocessors.md)
        - [Renderers](format/configuration/renderers.md)
        - [Environment Variables](format/configuration/environment-variables.md)
    - [Theme](format/theme/README.md)
        - [index.hbs](format/theme/index-hbs.md)
        - [Syntax highlighting](format/theme/syntax-highlighting.md)
        - [Editor](format/theme/editor.md)
    - [MathJax Support](format/mathjax.md)
    - [mdBook-specific features](format/mdbook.md)
    - [Markdown](format/markdown.md)
- [Continuous Integration](continuous-integration.md)
- [For Developers](for_developers/README.md)
    - [Preprocessors](for_developers/preprocessors.md)
    - [Alternative Backends](for_developers/backends.md)

-----------

[Contributors](misc/contributors.md)

Example from the mdbook documentation itself: https://rust-lang.github.io/mdBook/format/summary.html#example

With this, can organize the docs in a way where adding docs you wouldn't need to:

  • rename any files when adding new ones
  • add drafts easier (can add a draft without pushing it to the site)
  • be more intentional with placement and ordering of the docs

note: summary.md is just an example, for the site we might want a different (but just as easily modifiable) data file dedicated for docs organization/sorting

@ninjamuffin99 ninjamuffin99 added enhancement documentation (site) relating to the /documentation pages labels Apr 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation (site) relating to the /documentation pages enhancement
Projects
None yet
Development

No branches or pull requests

1 participant