Create offline docs with pandoc

Many open source projects use markdown and GitHub (Pages) for their docs. It is easier to maintain, while static page generators use them to render html. They often lack different file formats though. I do know about devdocs.io but I want them to be in a printable manner, not only offline, but totally off-the-grid like with no electricity at all. Don’t ask, I’ve my reasons.

I’m sure there are other projects written in markdown, but for now I’m only interested in Laravel and Vue. I cloned both repositories to disk, but it’s not like you could just run pandoc on them in a straight forward way. Both docs need to be sanitized first, merely to get a reasonably good result.

Laravel

The PHP language uses backslashes as namespace seperator. Some of them even start at the beginning of the line, to define classes and functions in the global namespace. The problem is, when pandoc starts to read these files it will interpret them as \(\mathrm{\LaTeX}\) fragments and complains about errors then. So I just doubled all the backslashes. But the problem didn’t end here. The Laravel docs usually add HTML anchors tags before headlines to create a table of contents. I think they don’t use plain markdown but some sort of flavour. So I removed them as well.

sed -i 's/\\/\\\\/g' *.md
sed -i '/.*name=".*"/d' *.md
cd /home/manu/git/docs

pandoc -o /home/manu/tmp/laravel.pdf \
       --pdf-engine=xelatex \
       --toc --toc-depth=3 \
       -V documentclass=report \
       -V papersize=a4 \
        installation.md \
        configuration.md \
        structure.md \
        homestead.md \
        valet.md \
        deployment.md \
        lifecycle.md \
        container.md \
        providers.md \
        facades.md \
        contracts.md \
        routing.md \
        middleware.md \
        csrf.md \
        controllers.md \
        requests.md \
        responses.md \
        views.md \
        urls.md \
        session.md \
        validation.md \
        errors.md \
        logging.md \
        blade.md \
        localization.md \
        frontend.md \
        mix.md \
        authentication.md \
        passport.md \
        authorization.md \
        encryption.md \
        hashing.md \
        passwords.md \
        artisan.md \
        broadcasting.md \
        cache.md \
        collections.md \
        events.md \
        filesystem.md \
        helpers.md \
        mail.md \
        notifications.md \
        packages.md \
        queues.md \
        scheduling.md \
        database.md \
        queries.md \
        pagination.md \
        migrations.md \
        seeding.md \
        redis.md \
        eloquent.md \
        eloquent-relationships.md \
        eloquent-collections.md \
        eloquent-mutators.md \
        eloquent-resources.md \
        eloquent-serialization.md \
        testing.md \
        http-tests.md \
        dusk.md \
        database-testing.md \
        mocking.md \
        billing.md \
        envoy.md \
        horizon.md \
        passport.md \
        scout.md \
        socialite.md

Vue

The Vue.js docs required more work.

awk -i inplace -v ORS='\r\n' 'FNR==1{print FILENAME}1' *.md
sed -i '/---/,/---/d' *.md
sed -i 's:/images/:images/:g' *.md
sed -i '1s/\.md//' *.md
sed -i '1s/^/# /' *.md
sed -i '1s/-/ /g' *.md
sed -ie '1s/\b\(.\)/\u\1/' *.md
cd /home/manu/git/vuejs.org/src/v2/guide 

pandoc -o /home/manu/tmp/vue.pdf \
       --resource-path="/home/manu/git/vuejs.org/src" \
       --pdf-engine=xelatex \
       --toc --toc-depth=2 \
       -V documentclass=report \
       -V papersize=a4 \
       installation.md \
       index.md \
       instance.md \
       syntax.md \
       computed.md \
       class-and-style.md \
       conditional.md \
       list.md \
       events.md \
       forms.md \
       components.md \
       components-registration.md \
       components-props.md \
       components-custom-events.md \
       components-slots.md \
       components-dynamic-async.md \
       components-edge-cases.md \
       transitions.md \
       transitioning-state.md \
       mixins.md \
       custom-directive.md \
       render-function.md \
       plugins.md \
       filters.md \
       deployment.md \
       single-file-components.md \
       unit-testing.md \
       typescript.md \
       routing.md \
       state-management.md \
       ssr.md \
       reactivity.md \
       comparison.md