Skip to content

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

@ninjamuffin99

Description

@ninjamuffin99

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions