Merge pull request #119 from dbu/separate-getting-started-from-basic

separate getting started from basic project

source/documentation.md

@@ -5,10 +5,12 @@ nav_name: documentation
 
 ---
 
-If you are looking to jump right in, make sure to check out the [Get Started][1]
-page. And as always, if you have questions please get in touch with the Sculpin
-[community][2]! We will try to get you answers quickly. :)
+If you are new to sculpin, check out the [Get Started][1] page. Then use the
+navigation on the left side of this page to read more on the topic you want to
+learn about.
 
+And as always, if you have questions please get in touch with the Sculpin
+[community][2]! We will try to get you answers quickly. :)
 
 [1]: {{site.url}}/getstarted/
 [2]: {{site.url}}/community/

source/documentation/basic-project.md

@@ -5,7 +5,7 @@ slug: basic-project
 ---
 
 A Sculpin project is capable of building exactly one static site. By default,
-Sculpin assumes a basic filesystem structure for any Sculpin project.
+Sculpin is configured to work with the following file structure:
 
     |-- app/
     |  |-- SculpinKernel.php           # Custom Sculpin kernel
@@ -14,62 +14,79 @@ Sculpin assumes a basic filesystem structure for any Sculpin project.
     |     |-- sculpin_site.yml         # Site meta data
     |     `-- sculpin_site_${env}.yml  # Env specific meta data
     |-- output_${env}/                 # Env specific generated files
-    |-- source/
+    |-- source/                        # Files in here are read and compiled
     |  |-- _posts/                     # Individual blog posts live here
     |  `-- _views/                     # Templates
-    `-- composer.json                   # Dependencies
+    `-- composer.json                  # Dependencies
 
 ---
 
-## Hello World Project
+Sculpin reads all files that are under the source directory. By default, this
+directory is called `source/` in your project root. For example, if you have a
+file called `source/index.md`, Sculpin will generate an
+`index.html` file in the output directory for you.
 
-To get started, try creating a simple "Hello World" project for Sculpin. By
-following these rules you can get started with a completely bare Sulpin site in
-no time!
+Besides the actual content, the `index.md` can also provide metadata. See
+[Sources]({{site.url}}/documentation/sources/) for the details.
 
-### Hello World Directory Structure
+The output folder can be uploaded to a web server as is. Because Sculpin is a
+static site generator, no PHP is used on the server.
 
-The directory structure of a Sculpin project is pretty simple. By default,
-Sculpin assumes that there will be a `source/` directory in your project root.
-Sculpin will read all of the files in your source directory.
+## Commands
 
-Create a file called `index.md` in your source directory. Sculpin will
-automatically translate this file to `index.html` when it generates your site.
+### Rendering your Site
 
-Your project should now look like this:
+The `generate` command looks for files in your source directory and generates
+static HTML files:
 
-    |-- source/
-       `-- index.md
+    vendor/bin/sculpin generate
 
-### Smallest Source File
+Your generated web site is now available in `output_dev`.
 
-The contents of `index.md` should look like this. We will talk about this in
-more detail later in the [Sources]({{site.url}}/documentation/sources/) section.
-For now, just type this in exactly.
+The `generate` command has two useful options:
 
-    ---
-    ---
+* `--watch` monitor the source directory and regenerate the site whenever a
+  source file is changed;
+* `--server` to serve files over HTTP with the built-in webserver.
 
-    # Hello World
+    vendor/bin/sculpin generate --watch --server
 
+Visit [localhost:8000](http://localhost:8000) to see your new static site!
 
-### Run and View
+The `generate` command also has a `--port` option, in case you need the web
+server to run on a different port:
 
-Your project now has everything Sculpin needs to know in order to generate your
-Hello World project. For now, we are going to use the `--watch` and `--server`
-flags. This tells Sculpin to *watch* the source directory for changes (so it
-can regenerate the site as you edit your files) and to *serve* the site using an
-embedded web server.
+    vendor/bin/sculpin generate --watch --server --port=8888
 
-    vendor/bin/sculpin generate --watch --server
+Besides using the `--server` option for `generate`, you have the following
+options for previewing the rendered pages locally.
 
-Visit [localhost:8000](http://localhost:8000) to see your new static site!
+#### Serve Command
+
+To serve files that have already been generated, use the `serve` command:
+
+    vendor/bin/sculpin serve
+
+#### Using a Standard Webserver
+
+The only special consideration that needs to be taken into account for standard
+webservers **in development** is the fact that the URLs generated may not match
+the path at which the site is installed.
+
+This can be solved by overriding the `site.url` configuration option when
+generating the site.
+
+    sculpin generate --url=http://my.dev.host/blog-skeleton/output_dev
 
+With this option passed, `{{ site.url }}/about` will now be generated as
+`http://my.dev.host/blog-skelton/output_dev/about` instead of `/about`.
 
-### Output
+## Environments
 
-The static files are placed in `output_dev`. Explore the `output_dev` directory
-to see what is happening behind the scenes:
+Sculpin knows the `dev` and `prod` environment. They allow you to have
+[different configuration settings by environment](configuration/). By default,
+the `dev` environment is used.
 
-    |-- output_dev/
-    |  `-- index.html
+When you want to build the final web site, run the command with the `--env=prod`
+option. The output of this command will be placed in `output_prod`. Upload the
+contents of this folder to your public website.

source/documentation/configuration.md

@@ -17,8 +17,8 @@ environments. By default Sculpin will generate your site for the `dev`
 environment. This is important to know because configuration can be based on
 environment.
 
-In order to generate your site for a production environment (`prod`), you need to
-specify this in your command line:
+In order to generate your site for a production environment (`prod`), specify
+the `--env=prod` option in your command line:
 
     sculpin generate --watch --server --env=prod
 

source/getstarted.md

@@ -67,7 +67,11 @@ Now we can use Sculpin to generate static files, watch for changes, and run a lo
 
     vendor/bin/sculpin generate --watch --server
 
-The `watch` flag tells Sculpin to watch the files for changes, and when changed to re-generate the site automatically. `server` launches PHP's web server which lets you see your work in progress from [localhost:8000](http://localhost:8000). After having run this command, a new directory, `output_dev`, will appear in your project, folder.
+The `watch` flag tells Sculpin to watch the files for changes, and when changed to re-generate the site automatically. `server` launches PHP's web server which lets you see your work in progress from [localhost:8000](http://localhost:8000). After having run this command, a new directory, `output_dev`, will appear in your project folder.
+
+The `generate` command also takes a `--port` option to run on a different port:
+
+    vendor/bin/sculpin generate --watch --server --port=8888
 
 Please note, the server command may crash from time to time. This is usually as a result of in-progress or partly-saved updates that can cause unrecoverable errors. If this happens, simply re-run the command - this usually resolves the issue, or helps provide more information about the cause.
 
@@ -119,6 +123,10 @@ If the content hasn't generated fully (perhaps there is a page missing for one o
     control-C
     vendor/bin/sculpin generate --watch --server
 
+Your blog post should now show up on the site. You can also see the generated file at
+
+    output_dev/blog/2020/01/07/time-travel/index.html
+
 ---
 
 ## Generate a Production-Ready Site
@@ -129,7 +137,7 @@ Create a production ready version of your static site:
 
     vendor/bin/sculpin generate --env=prod
 
-This will create the directory `output_prod` in your project's directory. The contents of this file can now be uploaded.
+This will create the directory `output_prod` in your project's directory. The contents of this directory are ready to be uploaded to a webserver.
 
 ---
 
@@ -143,13 +151,21 @@ Some common options are covered here:
 
     rsync -avze 'ssh -p 999' output_prod/ [email protected]:public_html
 
+You might want to use the `--delete` option to also delete files that got
+removed. (But first make sure that there are no other files in the target
+directory that you do not want to be deleted. When in doubt, try with the
+`--dry-run` flag first and check what rsync would do.)
+
 #### GitHub
 
-GitHub pages change from time to time, it is best to [read their instructions][1].
+For GitHub pages, you will commit the rendered files in a git repository.
+Please refer to the official [instructions on GitHub pages][1].
 
 #### Amazon s3 bucket
 
-The skeleton site comes with a `s3-publish.sh` script which you may edit and use to upload to your bucket.
+The skeleton site comes with a `s3-publish.sh` script which you may edit and
+use to upload to your bucket. You will need to install the `s3cmd` utility
+in your system for this script to work.
 
 ---