Offline editing via git
Amusewiki fully supports offline editing. This document describes how you can do it. It assumes you have some knowledge about how Git works. The internet is full of tutorials and documentation on this matter.
The procedure depends if you can access the server where Amusewiki is running with a system user, or if you need to use an external service like GitLab, GitHub, etc.
The instructions can be found at
/console/git, where you will find
the exact paths to use.
System user with SSH access
This is as simple as doing:
git clone ssh://amusewiki.org/var/lib/amusewiki/shared/repo/amw.git cd amw git pull # edit, commit... git push
The instance will pull the changes automatically.
Please ensure that your system user is member of the
Provide a remote reposity
Create a public repository on GitLab, GitHub or similar services (or on your own server).
Please initialized it empty, without any README,license, .gitignore or similar.
Get the repository HTTPS URL, e.g. https://example.com/git/test and
add it using the form you can find on the
/console/git page of you
Amusewiki instance. You can have one personal repository.
Now we are going to populate it and get it ready:
git clone https://amusewiki.org/git/amw cd amw git remote rename origin web # Please replace the example URL in the next line with the real one with SSH protocol git remote add origin email@example.com/git/test git push -u origin master git checkout -b upstream -t web/master
And the workflow is:
git checkout upstream git pull git checkout master git merge upstream # edit, commit... git push
The tricky part is that you need to visit
/console/git and press the
"fetch" button to pull the changes into the site. This doesn't happen
Naming convention in the archive tree
Creating new pages while via git is fully supported, but you have to pay attention to the naming convention, otherwise the texts will not show up.
Anyway, the recommended way to create files and attachments, it's to use the web interface, because the site is able to avoid conflicts and it's supposed to know where to place files. Also, if you're importing, you can use the HTML converter and save quite a few effort.
So the local editing is more useful for editing rather than uploading
new texts. You could, e.g., import, add the images (with some
placeholders in the text), place a
#DELETED wip header line, commit,
and resume the editing locally.
The maximum length is 95 characters in the range, ASCII letters and
digits only, separated by a single dash. No leading or trailing
dashes. The extension must be
filename is arbitrary and doesn't have to (even if it's recommended)
map to the real title set in the header via #title.
Special page's files go in the
specials directory, from the root of
the archive (1 level down).
Normal page's files go in a two level deep directory.
The top-level directory is a single character or digit, using the first character of the filename.
If the filename has is composed by more words (separated by a dash), the target subdirectory will be the first character of the filename and the first character of the second word of the filename. The rationale for this is that usually you want URIs in the form firstname-lastname-title, so there is an high chance to put all the files from the same author in the same directory.
E.g., john-doe-the-title have to go into the
j/jd directory, as
If the filename has only one word, then the second character used for
the subdirectory will be the last character of the filename. E.g.
In all the files, the
#title header line is mandatory.
Images belongs to the same directory as the corresponding text. You need to use a prefix to make it clear to which subdirectory it belongs, following the naming convention described in the previous section.
E.g., a file attached to the normal page
have a name like
my-test-whatever.png. Only PNG
and JPG images should be attached.
m/mt/my-test-file.muse m/mt/my-test-image-1.png m/mt/my-test-image-2.png
or, using the same scheme the web application is using:
m/mt/my-test-file.muse m/mt/m-t-image-1.png m/mt/m-t-image-2.png
PDFs attached to the page (via
#ATTACH filename.pdf header), must be
placed into the