10
edits
Julianharty (talk | contribs) (Added first draft of instructions for using zimwriterfs) |
Julianharty (talk | contribs) (→Configuring and Running Docker: Added heading for the examples) |
||
(5 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
= zimwriterfs instructions = | = 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. | 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 == | == Preparations == | ||
Some considerations can help you prepare your materials | Some considerations can help you prepare your materials | ||
Line 7: | Line 7: | ||
# Would you like to use the classic 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. | # Would you like to use the classic 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? | # 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. | # 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 <code>/Volumes/shared</code> in the running Docker image. | |||
<code> | |||
docker run -it -v $(pwd):/Volumes/shared -p 8888:8888 openzim/zimwriterfs | |||
</code> | |||
== Examples of using zimwriterfs == | |||
<code> | <code> | ||
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 --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 | |||
</code> | </code> | ||
== Test the ZIM locally == | == 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 |
edits