diff options
Diffstat (limited to 'docs/creating-a-site.txt')
| -rw-r--r-- | docs/creating-a-site.txt | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt new file mode 100644 index 0000000..41985c9 --- /dev/null +++ b/docs/creating-a-site.txt @@ -0,0 +1,181 @@ +.. slug: creating-a-site-not-a-blog-with-nikola +.. date: 2013/03/01 12:49:41 +.. tags: nikola, python +.. link: +.. description: + +Creating a Site (Not a Blog) with Nikola +======================================== + +One of the most frequent questions I get about Nikola is "but how do +I create a site that's not a blog?". And of course, that's because the +documentation is heavily blog-oriented. This document will change that ;-) + +Since it started, Nikola has had the capabilities to create generic sites. For example, +Nikola's `own site <http://nikola.ralsina.com.ar>`_ is a fairly generic one. Let's go +step by step on how you can do something like that. + +As usual when starting a nikola site, you start with ``nikola init`` which creates a +empty semi-configured site:: + + $ nikola init mysite + Created empty site at mysite. + +Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py`` +configuration file: + +.. code-block:: python + + + ############################################## + # Configuration, please edit + ############################################## + + + # Data about this site + BLOG_AUTHOR = "Roberto Alsina" + BLOG_TITLE = "Not a Blog" + # This is the main URL for your site. It will be used + # in a prominent link + SITE_URL = "http://notablog.ralsina.com.ar" + BLOG_EMAIL = "ralsina@kde.org" + BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola." + + # + # Some things in the middle you don't really need to change... + # + + post_pages = ( + ("pages/*.txt", "", "story.tmpl", False), + ) + +And now we are ready to create our first page:: + + $ nikola new_post -p + Creating New Post + ----------------- + + Enter title: index + Your post's text is at: pages/index.txt + +.. note:: The ``-p`` option in the ``nikola new_post`` command means we are creating a page and not a blog post. + +We can now build and preview our site:: + + $ nikola build + Scanning posts.done! + . render_site:output/categories/index.html + . render_sources:output/index.txt + . render_rss:output/rss.xml + : + : + : [Much more of the same] + + $ nikola serve + Serving HTTP on 127.0.0.1 port 8000 ... + +And you can see your (very empty) site in http://localhost:8000 + +So, what's in that ``pages/index.txt`` file? + +.. code-block:: rest + + .. title: index + .. slug: index + .. date: 2013/03/01 10:26:17 + .. tags: + .. link: + .. description: + + + Write your post here. + +Title is the page title, slug is the name of the generated HTML file +(in this case it would be ``index.html``) the date doesn't matter much in +not-blogs, same for tags and link. Description is useful for SEO purposes +if you care for that. + +And below, the content. By default you are expected to use +`reStructured text <http://nikola.ralsina.com.ar/quickstart.html>`_ but +Nikola supports a ton of formats, including Markdown, plain HTML, BBCode, +Wiki, and Textile. + +So, let's give the page a nicer title, and some fake content. Since the default +Nikola theme (called "site") is based on `bootstrap <http://twitter.github.com/bootstrap/>`_ +you can use anything you like from it: + +.. code-block:: rest + + .. title: Welcome To The Fake Site + .. slug: index + .. date: 2013/03/01 10:26:17 + .. tags: + .. link: + .. description: Fake Site version 1, welcome page! + + + .. class:: hero-unit span6 + + .. admonition:: This is a Fake Site + + It pretends to be about things, but is really just an example. + So, don't click this button, it leads nowhere. + + .. class:: btn + + Click Me! + + + .. class:: span5 + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis. + Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque + gravida quam a mi dignissim consequat. Morbi sed iaculis mi. Vivamus ultrices + mattis euismod. Mauris aliquet magna eget mauris volutpat a egestas leo rhoncus. + In hac habitasse platea dictumst. Ut sed mi arcu. Nullam id massa eu orci + convallis accumsan. Nunc faucibus sodales justo ac ornare. In eu congue eros. + Pellentesque iaculis risus urna. Proin est lorem, scelerisque non elementum at, + semper vel velit. Phasellus consectetur orci vel tortor tempus imperdiet. Class + aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos + himenaeos. + + [And more in the same vein] + +.. admonition:: TIP: Nice URLs + + If you like your URLs without the ".html" then you want to create folders and + put the pages in ``index.html`` inside them. Example:: + + nikola new_post -p pages/foo/index.txt + + which will create a page you could access as "http://yoursite.com/foo" + +And that's it. You will want to change the SIDEBAR_LINKS option to create a reasonable +"menu" for your site, you will want to hack the theme (check ``nikola help bootswatch_theme`` +for a quick & dirty solution), and you may want to add a blog later on, for company news +or whatever. + +.. admonition:: TIP: So, how do I add a blog now? + + First, change the ``post_pages`` option like this: + + .. code-block:: python + + post_pages = ( + ("pages/*.txt", "", "story.tmpl", False), + ("posts/*.txt", "blog", "post.tmpl", True), + ) + + And to avoid a conflict (because blogs try to generate ``/index.html``: + + .. code-block:: python + + INDEX_PATH = "blog" + + Create a post with ``nikola new_post`` and that's it, you now have a blog + in http://yoursite.com/blog (you may want to add links to it in SIDEBAR_LINKS of course). + +You can see the finished site in http://notablog.ralsina.com.ar and its full configuration in +http://ralsina.com.ar/listings/notablog/conf.py.html + +I hope this was helpful! |