tutorials icon indicating copy to clipboard operation
tutorials copied to clipboard

refactor: Reorganize project directory structure

Open ChenMiaoi opened this issue 5 months ago • 3 comments

Regarding the packaging logic, it has not been refactored for now. I consider this to be changes rather than a refactor.

  • Restructured documentation files into logical directories:

    • Moved tutorials and docs to pages/ with topic-based subdirectories
    • Consolidated platform docs under pages/platforms/
    • Organized toolchain docs under pages/toolchains/
  • Unified resource files under resource/ directory:

    • Board-specific resources moved to resource/de0_nano/
    • Simulator configs moved to resource/or1ksim/
    • All images centralized in resource/images/
  • Updated _config.yml and index.md to reflect new structure

This restructuring improves project maintainability and document discoverability by establishing a clearer and more logical file organization.

ChenMiaoi avatar Sep 02 '25 09:09 ChenMiaoi

I am a bit concerned about doing a refactor line this.

  • This will break links, i.e. https://openrisc.io/tutorials/docs/Linux.html would no longer work
  • Read: https://www.w3.org/Provider/Style/URI. (Cool URLs done change)

There are some links around the web that link to our tutorials so its not great to break it.

For new pages we can suggest a new structure to follow, but older pages should try to stay where they are or we need to add permalinks. https://jekyllrb.com/docs/permalinks/

stffrdhrn avatar Sep 03 '25 10:09 stffrdhrn

I put a few comments, but overall I think maybe we should not do this big refactor. I tried not to change to much when updating this as there might be links to the website.

If you think its not a big deal maybe we can reconsider.

This is indeed a problem, or... perhaps we can create a new repository for the new format, then migrate the old articles to the new repository for organization, and leave the address of the new tutorial in the old tutorials? Indeed, this change is too massive, and I'm starting to doubt myself now.

ChenMiaoi avatar Sep 03 '25 11:09 ChenMiaoi

I put a few comments, but overall I think maybe we should not do this big refactor. I tried not to change to much when updating this as there might be links to the website. If you think its not a big deal maybe we can reconsider.

This is indeed a problem, or... perhaps we can create a new repository for the new format, then migrate the old articles to the new repository for organization, and leave the address of the new tutorial in the old tutorials? Indeed, this change is too massive, and I'm starting to doubt myself now.

It is necessary to preserve the original repository URL, and the refactored format may also need to be revisited.

ChenMiaoi avatar Sep 03 '25 11:09 ChenMiaoi