Invarianz
commented
5 years ago First, thanks for clarifying the copy mechanism when putting assets into webpage/src/pages instead of webpage/assets/ it is now clear that it is much more sensible to put images, pdfs, etc. into webpage/assets/.
Now that I thought about reorganizing my webpage for a bit I came up with the following solution influenced by my own experiences.
Usually single webpages do not have that many images, code or maybe PDFs attached to them. When the webpage gets too long one tends to split logical parts into separate webpages. Let me show this with my specific example:
src/
├── index.md
├── config.md
├── _css/
│ └── ..
├── _html_parts/
│ └── ..
└── pages/
├── julia.md
├── judoc.md
├── physics.md
├── rpg.md
├── julia/
│ └── tips_tricks.md
├── physics/
│ ├── math/
│ │ └── statistics.md
│ ├── tests/
│ │ ├── hubbard_model.md
│ │ └── interacting_dot.md
│ └── theory/
│ ├── cdw.md
│ ├── hartree_fock.md
│ └── tdhf.md
└── rpg/
└── broken_hope.mdTo keep the logic in the webpage/assets/ folder I would propose a structure that reflects everything happening below src/ i.e. compared to the above folder structure the structure in webpage/assets/ would look like this:
assets/
├── index/
│ └── .. (All images, pdfs, scripts in index.md)
└── pages/
├── assets/
│ ├── judoc/
│ │ └── .. (.. in judoc.md)
│ ├── julia/
│ │ └── .. (.. in julia.md)
│ ├── physics/
│ │ └── .. (.. in physics.md)
│ └── rpg/
│ └── .. (.. in rpg.md )
├── julia/
│ └── assets/
│ └── tips_tricks/
│ └── .. (.. in tips_tricks.md)
├── physics/
│ ├── assets/
│ │ └── (empty)
│ ├── math/
│ │ └── assets/
│ │ └── statistics/
│ │ └── .. (.. in statistics.md)
│ ├── tests/
│ │ └── assets/
│ │ ├── hubbard_model/
│ │ │ └── .. (.. in hubbard_model.md)
│ │ └── interacting_dot/
│ │ └── .. (.. in interacting_dot.md)
│ └── theory/
│ └── assets/
│ ├── cdw/
│ │ └── .. (.. in cdw.md)
│ ├── hartree_fock/
│ │ └── .. (.. in hartree_fock.md)
│ └── tdhf/
│ └── .. (.. in tdhf.md)
└── rpg/
└── assets/
└── broken_hope/
└── .. (.. in broken_hope.md)So basically every markdown page in the src/ folder gets its own subfolder in the assets/ folder and with this one can reconstruct the layout of the src/ folder.
Now I believe that having this per page ordering negates the need for specific scripts/ img/ etc. folders in assets and also follows the logic of the src/ tree. So now one can just dump everything related to the markdown page into the specific folder and if needed can still create a substructure inside the per page folder (if one needs to further split between scripts, images etc.).
The only problem I see with this approach is that the links to files inside the markdown document could become quite long. This could be circumvented if every link in the markdown document (to scripts, images etc.) would point to its respective subfolder.
E.g. if i write  in cdw.md it automagically resolves to webpage/assets/physics/theory/assets/cdw/peierls.png. Or one could add a special variable for the subfolder belonging to a markdown page e.g. .
The same approach could be applied to scripts.
I hope this post was not too long, I wanted to make sure to cover weird corner cases with subfolders.
tlienart
See https://github.com/tlienart/JuDoc.jl/issues/147 for context
With respect to scripts, I think a simple solution to keep things organised would be to allow
input: \input{output}{phys/script1}
code (non-executed):
. ├── infra │ ├── favicon.png │ └── ... └── scripts ├── output │ ├── phys │ └── script1.txt ├── phys └── script1.jl
input: \input{output}{./code/script1}
src └── pages └── phys ├── page1.md ├── code │ └── script1.jl └── output # generated └── script1.txt