diff options
Diffstat (limited to 'doc/tips')
| -rw-r--r-- | doc/tips/embedding_content.mdwn | 35 | ||||
| -rw-r--r-- | doc/tips/github.mdwn | 67 | ||||
| -rw-r--r-- | doc/tips/upgrade_to_3.0.mdwn | 95 |
3 files changed, 197 insertions, 0 deletions
diff --git a/doc/tips/embedding_content.mdwn b/doc/tips/embedding_content.mdwn new file mode 100644 index 000000000..142acd16e --- /dev/null +++ b/doc/tips/embedding_content.mdwn @@ -0,0 +1,35 @@ +Content from sites such as YouTube can be embedded into a web page. Maybe +you want to do this. But you'll find that the [[plugins/htmlscrubber]] +doesn't let you. It blocks the tags used to embed such content, because +they can be abused in many evil ways. + +Some plugins have been written to try to work around this problem, by +whitelisting the html needed to embed things from a few sites like Google +maps, calendar, videos, and YouTube. The problem with these plugins is that +they have to be kept up to date to add new sites, and follow changes to the +html such sites use for embedding. + +(Digression: The real problem with the plugins is that they hide the +underlying trust relationship. If you decide to embed html from a site, +you'd better trust that site. And if ikiwiki lets you enter such html, it +needs to trust you.) + +The [[plugins/htmlscrubber]] offers a different way around this problem. +You can configure it to skip scrubbing certian pages, so that content from +elsewhere can be embedded on those pages. Then use [[plugins/lockedit]] +to limit who can edit those unscrubbed pages. + +For example, suppose your blog is all under `blog/*`, and you want +only yourself to be able to post there, and you'd like to be able to embed +youtube videos etc in your blog. Other users can edit some pages in the +wiki (Discussion pages, say), but not your blog posts. Then you could configure +ikiwiki as follows: + + htmlscrubber_skip => 'blog/* and !*/Discussion', + locked_pages => '!*/Discussion', + +More simply, you might want to allow yourself to embed content anywhere +on the wiki, but scrub content written on Discussion pages: + + htmlscrubber_skip => '!*/Discussion', + locked_pages => '!*/Discussion', diff --git a/doc/tips/github.mdwn b/doc/tips/github.mdwn new file mode 100644 index 000000000..cd1b479d1 --- /dev/null +++ b/doc/tips/github.mdwn @@ -0,0 +1,67 @@ +Here's how to set up a static wiki or blog using ikiwiki with no hosting +feeds. Everything is hosted on github, both the git repository and the web +site. Your laptop is used to generate and publish changes to it. + +This is possible because github now supports +[github pages](http://github.com/blog/272-github-pages). + +Note that github limits free accounts to 100 mb of git storage. It's +unlikely that a small wiki or blog will outgrow this, but we are keeping +two copies of the website in git (source and the compiled site), and all +historical versions too. So it could happen. If it does, you can pay github +for more space, or you can migrate your site elsewhere. + +## github setup + +* Go to [github](http://github.com/) and sign up for an account, if you + haven't already. +* Be sure to add your laptop's ssh key to it so you can push + to github. +* Create a repository on githib named `$YOU.github.com`, substituting your + username. This repository will be used to publish your compiled website. +* Create a repository on github named `$YOU` (or anything else you like). + This repository will be used to publish the source of your website. + This is actually optional. + +## local setup + +* On your laptop, create two empty git repositories to correspond to the + github repositories: + YOU=# your github username here + mkdir ~/$YOU.github.com + cd ~/$YOU.github.com + git init + git remote add origin git@github.com:$YOU/$YOU.github.com.git + mkdir ~/$YOU + cd ~/$YOU + git init + git remote add origin git@github.com:$YOU/$YOU.git +* Add some wiki pages, such as an `index.mdwn`, to `~/$YOU`, and check them + in and commit them to git. You need something to push to github. Run + `git push origin master` to push the source pages to github. + +## publishing to github + +* Now build your wiki with a command such as: + ikiwiki ~/$YOU ~/$YOU.github.com --refresh +* Each time you build the wiki you will need to commit the changes + to git, and push the compiled pages to github: + cd ~/YOU.github.com + git add . + git commit -a -m update + git push origin master + +Your wiki will show up at `http://$YOU.github.com/` within ten +minutes after the first push, and changes you push to it from then on +should show up immediatly. + +## enhancements + +You can follow the instructions in [[laptop_wiki_with_git]] to set up an +editable version of your wiki on your laptop. Then you can use the web +interface for editing. You'll still need to follow the instructions above +to publish your changes to github. + +It would also be possible to teach ikiwiki to push compiled pages to github +itself via a plugin, as was done with the [[plugins/amazon_s3]] plugin. Not +done yet! diff --git a/doc/tips/upgrade_to_3.0.mdwn b/doc/tips/upgrade_to_3.0.mdwn new file mode 100644 index 000000000..b8a75aeca --- /dev/null +++ b/doc/tips/upgrade_to_3.0.mdwn @@ -0,0 +1,95 @@ +Version 3.0 of ikiwiki makes some significant changes, which +you will need to deal with when upgrading from ikiwiki 2.x. + +[[!toc ]] + +## setup file format change + +The layout of the setup file changed in a significant way in version 2.60 +of ikiwiki. If you have not changed yours to the new format, now would be a +good time to do so. Some new features, like the [[plugins/websetup]] +interface, need the new format setup file. + +You can convert old setup files into the new format by running +`ikiwiki-transition setupformat your.setup` + +## moving settings from Preferences page + +The admin preferences page used to have settings for allowed attachments, +locked pages, and banned users. These three settings have moved to the +setup file, and will no longer appear on the admin preferences page once +your wiki is upgraded to 3.0. + +You can move these preferences into the setup file by running +`ikiwiki-transition moveprefs your.setup; ikiwiki -setup your.setup -refresh -wrappers` + +(Make sure you have converted the setup file to the new format first.) + +## prefix directives + +In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has +changed, requiring that the directive start with a bang: + + \[[!directive ...]] + +If you would like to keep the old syntax, it is still supported, add the +following to your setup file: + + prefix_directives => 0, + +To convert to the new syntax, run +`ikiwiki-transition prefix_directives your.setup` + +(And then commit the changes it makes to pages in your srcdir.) + +## GlobLists + +In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no +longer supported. A GlobList contains multiple term, but does not separate +them with "and" or "or": + + sandbox !*/Discussion + +To convert this to a modern PageSpec, simply add "and" or "or" as +appropriate between terms: + + sandbox and !*/Discussion + +GlobLists have been deprecated for more than two years. If your wiki dates +to the ikiwiki 1.0 era, you should check it for any that might have lurked +unnoticed in it since back then. Ikiwiki version 2.72 will print warnings +about any GlobLists it sees. + +## aggregateinternal + +If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start +to aggregate feeds to special "internal" pages. + +If you don't want this change, you can add the following to your setup +file: + + aggregateinternal => 0, + +Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin: + +1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated + pages -- such as those in inlines. Put "internal()" around globs + in those PageSpecs. For example, if the PageSpec was `foo/*`, it should + be changed to `internal(foo/*)`. This has to be done because internal + pages are not matched by regular globs. +2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html` + files in the srcdir. The command to run is + `ikiwiki-transition aggregateinternal your.setup`, +3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`) + +## embed / googlecalendar + +The googlecalendar plugin has been deprecated for a long time, and is +removed in 3.0. + +The embed plugin is also now deprecated, though not yet removed. + +If you use either plugin to embed content from google, youtube, etc, +into your wiki, you should instead configure the [[plugins/htmlscrubber]] +to skip sanitising some pages, via the `htmlscrubber_skip` setting. +See [[embedding_content]] for examples. |