antwarjs / antwar Goto Github PK

The idea is that the api should return a promise (say build.then(...).catch(...)) and take console in config -> more control over output.

We'll want to use lazy loading (see https://github.com/rackt/react-router/tree/master/examples/partial-app-loading) here. Ie. we generate an index and a fragment for each page. Index will work as an entry point. After a client hits an index initially, it will consume those fragments after that. Thanks to Webpack's magic, we should get the needed bundles quite easily.

We should open a hook to insert things into the head of the site, for example meta tags, stylesheet links, etc.

We need a more stable solution for plugging functions into the build step, for generating url:s, content, titles etc. Both themes and plugins should be able to plug into this.

Entry point:

module.exports = {
    Body: require('...'),
    Nav: require('...'),
    configuration: {} // webpack specific stuff
};

Ie. we should match against **/*.md. glob module is excellent for this purpose.

This will allow arbitrary layout for the directory. Note that there should be some way to define post ordering through configuration to make this sensible. Example:

antwar.config.js

module.exports = {
    sorting: function(a, b) {
         // see JS sort. both a and b contain regular post metadata after shaping through plugins
    },
};

Example:

// basic
function basicUrlify(post) {
    return post.category + '/' + slugify(post.title);
}

// multiple urls per post
function multipleUrlify(post) {
    return [
       post.category + '/' + slugify(post.title),
       dateify(post.date) + '/' + slugify(post.title)
    ];
}

// redirect
function redirectUrlify(post) {
    var to = dateify(post.date) + '/' + slugify(post.title);

    return [
        {
            from: post.category + '/' + slugify(post.title),
            to: to,
        },
        to,
    ];
}

You would just have one of these mappings somewhere in the project configuration. The nice thing is that it's very flexible and you can do 1-1, N-1 type of mappings and even rerouting (last case).

Given internally it's just a react-router Link, this would give us nice validations (less issues during development).

Had a friend try the installation process and it complained about coffeescript dependency. Should be investigated further. Possibly the default-theme should have an explicit dep.

It should be possible to hook into the rendering process through a plugin API. Example configuration:

plugins: {
    // the tag plugin would operate based on posts tags metadata + provide a data source that can be used for routing
    // ie. it would shape ['foo', 'bar'] into [{name: 'foo', url: '...', posts: [...]}, {name: 'bar', url: '...', posts: [...]}]
    // you can see url shaping function below
    'antwar-tags': {},
    // there could be an image plugin to deal with thumbnail generation
    'antwar-images': {}, // is this actually needed here? push to higher level?
    'antwar-popular-posts': { // https://www.npmjs.com/package/ga-server
        id: '...',
        clientEmail: '...',
        privateKey: '...'
    }, // adds popularity field for each post
},

Each plugin is a NPM plugin with a matching name. It can take an object containing options related to it.

Interface of a plugin can look like this:

module.exports = function(meta) {
    // do something with the meta, manipulate somehow ie. see examples above

    ...

    return meta;
};

See https://www.npmjs.com/package/webpack-notifier . This should help us to give nicer output in case theme or something fails during development.

In general it should be possible to author posts in whatever format you like. We can provide some defaults at boilerplates but it should be able to complement/replace those with other solutions.

The main benefit here is that you can apply additional loaders (ie. highlight) on content easily if we do this.

The only problem I see here is that YAML headmatter has a special purpose in our system (gets parsed and passed to post template) so that might take some thinking. I guess if it exists, we'll inject the data. Otherwise just skip it.

We should add hooks for plugins (and themes?) in the posts processing.

Core (paths.js) collects all the posts and process them one by one. We should lift out the processing to a separate file, then add hooks for plugins before and after the core processing. We should also add a hook for replacing the core processing.

Something like preProcess(), process() and postProcess().

The tag plugin would operate based on posts tags metadata + provide a data source that can be used for routing. Ie. it would shape ['foo', 'bar'] into [{name: 'foo', url: '...', posts: [...]}, {name: 'bar', url: '...', posts: [...]}].

Example configuration

'antwar-tags': {
    route: function(meta) {
        // return path to tag
    }
},

Now we're expecting the user to choose a theme among the ones available on npm (not too many at the moment) and they leave little room for customization. It would be nice if we could pick up a theme from the site folder aswell.

There should be a validator (JSON schema) that allows us to make sure configuration contains the right data. We can also deal with defaults and possible extra fields (not allowed) there.

Now it outputs to a fixed location which isn't great.

• i did a bunch of cli tweaks including that querystring thing. also renamed -g --github as -D --deploy since it's a generic utility
• i started thinking that maybe antwar.config.js should be split into two: antwar.config.js and antwar.site.js. former would be just what we have at site field right now while latter would be site specific meta available for each page on rendering stage
• this would reduce nesting and make our code a little simpler. in addition it would be easier to just copy a nice antwar.config.js across projects without having to tweak it
• you would just define a custom antwar.site.js per site then
• also port setting seems too generic. maybe we should have something more specific per target (ie. serve + deployment blocks)
• i won't do any changes as i'll wait for your feedback. gotta look into some of the core issues next

• eldh 2 hours ago
• sounds all good to me. I realized I don’t have anything other than site in the three antwar.config.js files I have here... and yes, being able to define both serve and dev ports would be very good.

Now the build relies a lot on sync versions of fs functions. I'm not sure how much these actually slow down things but it might be a nice idea to port them to async.

Fix some basic logo and branding stuff,

We should allow pages written in markdown. Right now we expect pages to be React components, but we could just pass .md files in the pages folder to a Page template.

Ie. index using http://lunrjs.com/ and then write a UI using React. This could get a little problematic with bigger amounts of data, though. In that case we might want to rely on something external like http://www.algolia.com/ (separate plugin?).

When you have a demo ready to show, please close the ticket and add to react.rocks, thanks!

The current solution is a hack, and it causes a warning when running the dev server.

• This should generate similar results as a real isomorphic server!

Seems innocuous but having the first msg an error looks bad--

$ antwar --init rrocks_blog
{ [Error: Cannot find module '/Users/Jeff/repos/antwar.config.js'] code: 'MODULE_NOT_FOUND' }
Starting to initialize project

A theme should be able to declare its Webpack dependencies and export related configuration through its entry point. Example:

module.exports = {
    Nav: require('./Nav),
    ...
    configuration: {} // webpack configuration should go here
};

Configuration

'antwar-popular-posts': { // https://www.npmjs.com/package/ga-server
    id: '...',
    clientEmail: '...',
    privateKey: '...'
}, // adds popularity field for each post

This can be developed on top of JSON output of https://github.com/bebraw/blogger2ghost . Just need to convert that JSON to Markdown with suitable YAML headmatter.

These can be pushed to themes now.

Defaults to antwar.config.js at project root (modeled after Webpack convention).

Example:

module.exports = {
    theme: 'antwar-default-theme', // point to theme by its NPM name
    output: 'build', // where to output
    ... // add custom properties as needed (available at templates)
};

It might be nice to set up something browser based. Generally this is something that's lacking with static blogging tools.

The idea is that you would hit antwar-editor (or similar command). That would open up the blog in browser and show basic editing tools in some panel etc. You should be able to edit existing posts here, create new ones and publish drafts.

Technically speaking antwar would run a local server that would operate as a proxy between the user and the file system. It should be able to deal with git commits as well.

I think this sort of thing would bridge the gap between traditional blogging solutions (WordPress, Ghost) and static ones.

Later on this could be developed into a standalone service which you could access over web but that goes way beyond the scope of this issue.

Invoking the command by itself does nothing at all. Seems more useful/common to show help in this case.

Related to #44.

It should be possible to attach previous/next page to page metadata. This should run after sorting pages.

The idea here is that then you can use this information on UI level and build a nice navigation from post to another.

It would be nice if it was possible to generate thumbnails for blog post images. I expect this would be some sort of custom tag.

Given a blog might have a lot of images, I guess this should be an incremental process (generate just missing thumbnail images to the build assets?).

There's currently no nice way to include custom styles on top of a theme. We should be able to add that through the config.

Did the following

npm install -g antwar-cli
antwar --init rrocks_blog

Errors out--

/usr/local/lib/node_modules/antwar-cli/lib/init.js:13
    console.info('Fetching boilerplate metadata');
            ^
TypeError: Cannot call method 'info' of undefined
  at Object.module.exports [as init] (/usr/local/lib/node_modules/antwar-cli/lib/init.js:13:13)
  at main (/usr/local/lib/node_modules/antwar-cli/index.js:49:13)
  at Object.<anonymous> (/usr/local/lib/node_modules/antwar-cli/index.js:13:1)
  at Module._compile (module.js:456:26)
  at Object.Module._extensions..js (module.js:474:10)
  at Module.load (module.js:356:32)
  at Function.Module._load (module.js:312:12)
  at Function.Module.runMain (module.js:497:10)
  at startup (node.js:11

Is there supposed to be a .js? This is "doubly static", right?

Provide support for drafts.

Add a drafts folder, and provide methods in paths.coffee and pathsMixin to get the drafts.

There's currently no nice way to create dynamic pages (that include scripts in some form). This needs to be fixed, naturally.

I don't know which is the best approach, but generating entrypoints for webpack is an idea worth investigating.

http://antwarjs.github.io/getting-started/ looks good. Maybe link to it from main Readme?

Also, seems like "npm install antwar-cli" should be -g?

This probably got broken somewhere within CS -> JS conversion process. Just need to figure out what has changed and resolve.

This should consume Disqus required metadata as input and output Disqus tags at end of posts (pages too?).

I wonder if this should be a totally automated process. Ie. you would just npm install the plugin and configure it and everything would just work by default.

Support for GA.

Could easily be done in the theme (i think).

Currently it's CoffeeScript. Maybe start with a port to vanilla JS and then work from there.

The plugin configuration should give proper access to RSS meta.