Difference between revisions of "Zimwriterfs instructions"
Julianharty (talk | contribs) (→Configuring and Running Docker: Added heading for the examples) |
|||
| Line 5: | Line 5: | ||
# Can it be read and navigated in a mainstream web browser e.g. using <code>file://localhost/mycontent</code> (replace mycontent with the correct URL) | # Can it be read and navigated in a mainstream web browser e.g. using <code>file://localhost/mycontent</code> (replace mycontent with the correct URL) | ||
# Would you like to use the | # Would you like to use the recommended ZIM file internal structures? e.g. <code>./-/</code> for CSS and <code>./A/</code> for articles (in HTML format), etc.? If so, there's no need to use the <code>--uniqueNamespace</code> command-line option. Otherwise please use it. | ||
# Have you identified your welcome page and got a suitable icon? | # Have you identified your welcome page and got a suitable icon? | ||
# Have you created a shared location available to the running Docker image to make the content easier to access by zimwriterfs?[1] | # Have you created a shared location available to the running Docker image to make the content easier to access by zimwriterfs?[1] | ||
Revision as of 19:14, 20 April 2020
zimwriterfs instructions
Here are some notes on how to prepare your materials and use `zimwriterfs`. The notes are incomplete as they're based on my limited experience using the tool in the prebuilt Docker Image. The Docker file is available at https://hub.docker.com/r/openzim/zimwriterfs/
Preparations
Some considerations can help you prepare your materials
- Can it be read and navigated in a mainstream web browser e.g. using
file://localhost/mycontent(replace mycontent with the correct URL) - Would you like to use the recommended ZIM file internal structures? e.g.
./-/for CSS and./A/for articles (in HTML format), etc.? If so, there's no need to use the--uniqueNamespacecommand-line option. Otherwise please use it. - Have you identified your welcome page and got a suitable icon?
- Have you created a shared location available to the running Docker image to make the content easier to access by zimwriterfs?[1]
- Would you like to distribute to a large base of users who may use a variety of machines and storage options? If so, it will be important to split the ZIM file into no more than 2GB chunks.
[1] I added a shared folder so I could easily share data between the running Docker image and my macbook. This had to be configured using the command line. See https://github.com/rocker-org/rocker/wiki/Sharing-files-with-host-machine for tips on how to do this.
Configuring and Running Docker
Again some qualifications:
- I've limited experience in using Docker.
- This worked for me but might need tweaking for others.
- I use Kitematic (available in Docker) to obtain a shell in the running Docker image.
Here's how to share the current folder with the Docker image. The shared folder is at /Volumes/shared in the running Docker image.
docker run -it -v $(pwd):/Volumes/shared -p 8888:8888 openzim/zimwriterfs
Examples of using zimwriterfs
zimwriterfs --uniqueNamespace -w index.html -f icon.png -l EN -t "Testing Heuristics" -d "Early cut of the testing heuristics material." -c "Julian Harty" -p "Commercetest Ltd." /Volumes/shared/dist/ /Volumes/shared/th-ln.zim
zimwriterfs -w index.html -f tess.png -l EN -t "Visions for Teaching and Learning", -d "Sample TESS content: Week 1" -c "Open University" -p "Julian Harty" /Volumes/shared/week_1__visions_for_teaching_and_learning.html/ /Volumes/shared/week1.zim
Test the ZIM locally
Use at least one reader e.g. a Kiwix app or server to test the ZIM file contains the expected contents. The Welcome page is displayed, CSS is applied, Images appear, etc.
Known issues
Symlinks to content cause zimwriterfs to abort https://github.com/openzim/libzim/issues/16