Support multiple HTML pages to generate small websites
epogrebnyak opened this issue · comments
In a case when you can have several handouts the output folder may get cluttered. This may be a case when one wants to render several files and link them to display in a static site generator, eg via Github Pages.
I propose the html components/dependecies can be stored in a subfolder filename.html.files, which will make output folder cleaner.
This behavior is similar to how a browser, eg Chrome will save an html page to a local disk.
In other words, if you have multiple handouts in sibling directories, you may only want the style file (and maybe JavaScript libraries) stored once?
I'm wondering if there is an actual use case for this, but let's leave this open to discuss and see how many people are interested in this feature. I wouldn't introduce a specific directory structure just now, because it seems like unnecessary added complexity.
unnecessary added complexity.
Flat is definitely simplier, but let's consider a case where you might want more than one 'handouts' in one project. Every time they will overwrite index.html, in current configuration.
If you want two handouts, you can already do:
doc1 = handout.Handout(outdir1)
doc2 = handout.Handout(outdir2)Markdown links between them should also work if they are in the same parent directory.
The main aspect that I see could be improved is to not have two copies of the CSS and JS files. Is there anything else you see missing for this?
Making different directories is certainly a good clean way for several files. My concern is that appropriate hint or workflow advice should be somewhere is the documentation.
I’d be happy to see an advice like “in case you are rendering several handouts in one project consider putting each handout to a separate directory”:
model.py
---------
doc = handout.Handout("output/model")
demo.py
---------
doc = handout.Handout("output/demo")
Maybe add a documentation tag to this issue and close for now?
not have two copies of the CSS and JS files.
True, but I also can stick to "all the output in a single folder" model for a while. Single CSS / JS for several html is good, but can make links more complicated, will need to make assumptions about folder structure.
As a more distant option can make another argument assets_directory for Handout(directory, title, assets_directory), but it does not seem a very good solution yet.
Sounds good. Let's collect key topics and then put together a user guide: #20.
I like the idea of passing an assets directory into the constructor if this there are multiple users that would benefit from this. Anybody who's like this, feel free to upvote the comment above.