This article is intended for people who already have an user account for our Subversion server. It provides a short introduction about how to upload and manage articles for this site.
The source HTML files of all articles on this site, as well as all template files which make up the general look of this site, are contained and managed by our regular Subversion server. You may also browse the source article files with our SVN server's web frontend.
So to start, first checkout the SVN repository of this site:
svn co https://svn.linuxsampler.org/svn/doc doc.ls.org
Now you have downloaded this site's source files with a directory structure that should look like this:
docbase directory contains all articles of this site
(the content), whereas the
tmpl directory contains all files
which make up the look of this site (layout). Most notably the
index.html file, in the directory structure shown above, is
the main template file for this site.
Modifying an Article
To modify an existing article, simply open the respective HTML file
(which is located somewhere below the
docbase directory) with a
text editor of your choice. You can preview the article locally with your
web browser while doing your modifications. After you are done with your
changes, simply commit the modified articles to our Subversion repository:
- cd doc.ls.org
- svn commit
Like with commits regarding all our software projects, you must always supply a comment with each one of your Subversion commits. Once your files are commited successfully, our system will process the files and rebuild this site automatically. Note that changes regarding articles are also displayed on our frontsite. The same rules apply like with our other software commits, that is a SVN comment that begins with a star character like:
* Changed article "Foo".
Will cause the commit to be displayed in the change log on our frontsite. If you omit the star like:
- Changed article "Foo".
Then your article changes will be a "silent" commit and it will not be displayed on the frontsite. Please only use such silent commits for trivial changes, i.e. when fixing typos and other very trivial things like that.
Our site's software will try to solve problems on its own as much as possible in order to avoid bothering you. However if your modifications introduced some kind of severe error which the software is not able to solve on its own, then you will automatically get an email concerning the problem introduced by you. In this case please resolve the issue manually as being told by the software and then commit your changes again. You will also get an automated email in this case once your new changes actually solved the problem(s) with a "everything is now back at normal" message. As long as there is a severe yet unresolved problem, the site's appearance will remain in the previous, last valid state.
Adding an Article
To add a new article for this site, simply add the new article's HTML
file somewhere below the
docbase directory. Please don't
add the new file directly into the
docbase directory, because
in that particular directory there should always be only one HTML file
root.html - our site's front page). So rather create a
new directory and add your new HTML file there, i.e. like this:
Neither the directory name
my_new_article, nor the HTML
01_foo.html will directly be exposed to the readers
of this site. So the name of the directory is almost irrelevant regarding
the precise URL name or article name. Only the directory structure
(the tree) is relevant for the site, because it defines which article shall
be located "under" which other article(s), which effectively defines its
appearance in the navigation bar, as well as how the URL of the article
If you are writing an article that you want to be splitted into separate pages, or if you want to add articles that shall directly be associated with each other, then you can add them to the same directory like this:
Which will cause those articles to get "Next" and "Previous" buttons to browse between them conveniently. The prefixed numbers of the HTML files define the order in which they are linked with each other and appearing this way on our site.
Once you are done, commit your new article(s) to our Subversion server:
- cd doc.ls.org/docbase
- svn add my_new_article
- svn commit
So far you should only commit .html files and image files (.png, .jpg, .gif) to our Subversion server. All other files will be ignored. Please also make sure your images are not too large.
Changing the Look
If you just want to modify the look of your article, you may just add
regular CSS code to your article's HTML source file. If you rather want to change
the overall appearance of the entire website, then have a look at the previously
will be used by our site's software to generate all pages of this
website, that is it takes that file as skeleton, and replaces its
<article> section with the
respective content of the article's source HTML file. So that
tmpl/index.html file defines the HTML code that will be generated
for each page, which however is essentially just the data model of the page,
not its actual appearance. Note that this file is a real HTML file, not
a fragmented exotic file filled up with markers or something, like it is
usually the case with template files of other systems. In other words: you can simply
tmpl/index.html with your web browser and immediately
test your style changes locally before commiting them.
The actual visual appearance (view) for the website is defined by the
tmpl/css/main.css. That's because this CSS file is
currently linked in the
<head> section of
tmpl/index.html template file. So it is not
hard coded in our software.
This mentioned CSS file is taken verbatim as-is. That's because
all files contained in subdirectories below the
simply be copied as they are. So open
your local machine with a web browser, modify the CSS files etc. until
you are satisfied with the new look, and finally commit your changes to our
That's it! If there is something unclear, or if you encounter any kind of problem, please contact Christian.