ability to include custom templates

DimitarChristoff commented 12 years ago

This is more of a feature-request / chore than a bug.

Have a look at this: http://dimitarchristoff.github.com/Epitome/#epitome-model

scroll down, keep scrolling and look at the left side menu changes. which is fine, for as long as I keep on adding the code every time I regenerate the docs.

Basically, I want to be able to add custom content blocks to the generated html file that will include my local scripts/css before I push to gh-pages.

Would it be possible to extend .documentup.json to have a header: "docs/header.html" or something - will negate the need to do theme support for now as people will be able to override whatever they like.

I am open to other suggestions on applying local transforms. Only thing I can think of right now is to write a node script that gets the repo compiled docs, then outputs it into jsdoc or phantomjs in a pseudo dom, appends the scripts / transforms elements, reads the document html and writes it to a file.

DimitarChristoff commented 12 years ago

erm. I did what I had suggested.

#!/usr/bin/env node
var dom = require('jsdom'),
    request = require('http'),
    fs = require('fs'),
    build = {
        host: 'documentup.com',
        path: '/DimitarChristoff/Epitome'
    },
    compile = {
        host: 'documentup.com',
        path: '/DimitarChristoff/Epitome/recompile'
    },
    writeDocs = function() {
        request.get(build).on('response', function(response) {
            var html = '';

            // read the data
            response.setEncoding('utf-8');
            response.on('data', function(chunk) {
                html += chunk;
            });
            response.on('end', function() {
                // now, create a jsdom document out of the response, injecting the extra scripts
                dom.env(html, [
                    'http://ajax.googleapis.com/ajax/libs/mootools/1.4.5/mootools-yui-compressed.js',
                    'js/moostrap-scrollspy.js',
                    'js/docs.js'
                ],
                function(errors, window) {
                    var head = window.getDocument().getElement('head');

                    // add custom stylesheet
                    new window.Element('link', {
                        href: 'css/docs.css',
                        type: 'text/css',
                        rel: 'stylesheet'
                    }).inject(head);

                    // move the scripts to the head
                    window.document.getElements('.jsdom').removeClass('jsdom').inject(head);

                    // fix doctype
                    html = ['<!DOCTYPE html>', window.document.innerHTML].join('\n');

                    // write to file.
                    fs.writeFile('index.html', html, function(error) {
                        if (error) {
                            console.log('Failed to create index.html. ', error);
                        }
                        else {
                            console.log('index.html was created');
                        }
                    });
                });
            })

        }).on('error', function() {
            console.log('Failed to get documentation.');
        });
    };

// get going. compile first, then get the new docs.
request.get(compile, function() {
    // give it some time to generate
    setTimeout(writeDocs, 2000);
});

basically, ./build.js will go, force recompile, then fetch the built file from your server, then add 3 js files and 1 css file to a mock dom, then write the resulting file into index.html

jeromegn commented 12 years ago

Oh, I see what you mean.

Yes that's nifty. For now there's absolutely no JavaScript loaded client-side DocumentUp. Trying to keep it as lightweight as possible.

I'll be adding some soon. At some point it just becomes necessary.

About your script. You can also use the afterRender method documented here: http://documentup.com/#gh-pages/configuration :) I know, I need to surface this better.

Will definitely keep this feature in mind when I go all JS on DocumentUp.

DimitarChristoff commented 12 years ago

well - this is about being able to include stuff within the markup returned from the server - css, js, whatever. i choose to do it on the server as this build.js is a part of a more complicated script that checks out gh-pages, runs it, stages it, pushes it and goes back to master.

embedding via a JSONP through javascript call means google cannot access the data, but yes, I realise you could hook into the DOM post render that way.

jeromegn / DocumentUp

ability to include custom templates #52