/scalate-website/src/documentation/siteGen.page

  1---
  2title: Site Generator
  3in_menu: false
  4sort_info: 2
  5--- name:overview
  6# Site Generator
  7
  8Create that static website with Scalate
  9
 10--- name:content pipeline:jade
 11
 12.left
 13  :markdown
 14    # Overview
 15
 16.right
 17  :markdown
 18    Scalate can be used to create a static website reusing all of the various 
 19    Scalate template languages, filters, wiki markups and pipelines. 
 20
 21.left
 22  :markdown
 23    # Creating a Site
 24
 25.right
 26  :markdown
 27  
 28    The quickest way to get started is to [install the Scalate Tool](installing.html) then run
 29
 30        scalate create sitegen mygroup myartifactid
 31
 32    This creates an example sitegen project in the myartifactid directory.
 33
 34    Inside the project run the following
 35
 36        mvn jetty:run
 37    
 38    Then open [http://localhost:8080/](http://localhost:8080/) and you should see the styled website.
 39
 40    The source for the site in wiki markup or templates are all in the `src` directory.
 41
 42    However you can also use the [Console](console.html) to edit the templates directly. 
 43
 44    Just open the console via the top right icon. You will then see links to the page you are 
 45    looking at along with the layout template used to render the current page. Clicking on the link 
 46    will open the wiki page or template in your editor. Refer to the [Console](console.html) for 
 47    details of changing your default editor.    
 48
 49    When you change a file and hit save you can hit reload in your browser to see the newly 
 50    rendered page. Whether you change a wiki page, an include or a template you will always see the 
 51    most up to date page in your browser.
 52
 53.left
 54  :markdown
 55    # Generating the static site
 56
 57.right
 58  :markdown
 59
 60    ### Maven
 61  
 62    To generate the static site run
 63
 64        mvn install
 65    
 66    This will invoke the **scalate:sitegen** plugin which generates the static website to the 
 67    **target/sitegen** directory.
 68
 69    There's also a **scalate:sitegen-no-fork** plugin goal available that can be used to configure 
 70    additional/different executions of the goal in an existing build.
 71
 72    ### sbt
 73
 74    To create a sitegen project in sbt, first add the plugin dependency to
 75    `project/plugins/Plugins.scala`:
 76
 77    {pygmentize:: scala}
 78    lazy val scalate_plugin = "org.fusesource.scalate" % "sbt-scalate-plugin_${scala_compat_tag}" % "${project_version}"
 79    {pygmentize}
 80
 81    Then mix the `org.fusesource.scalate.sbt.SiteGenWebProject` into your
 82    web project, along with the Scalate dependencies.  For example:
 83
 84    {pygmentize:: scala}
 85    import org.scalate.fusesource.sbt.SiteGenWebProject
 86
 87    class MySiteGenProject(info: ProjectInfo) extends
 88          DefaultWebProject(info) with
 89          SiteGenWebProject {
 90
 91      lazy val scalate_core = "org.fusesource.scalate" % "scalate-core_${scala_compat_tag}" % "${project_version}"
 92      lazy val servlet = "javax.servlet" % "servlet-api"% "2.5"
 93      lazy val logback = "ch.qos.logback" % "logback-classic" % "0.9.26"
 94
 95    }
 96    {pygmentize}
 97
 98    This creates a ***generate-site*** action, which is run as a dependency of
 99    the ***package*** action.  The static web site is generated to the
100    ***target/sitegen*** directory.
101
102.left
103  :markdown
104    <h1 id="deploy">Deploying the static site</h1>
105    
106.right
107  :markdown
108
109    Before you start trying to deploy you need to add a `distributionManagement` section 
110    to your pom.xml. For example projects hosted on the 
111    [FuseForge](http://fusesource.com/forge/) tend to use something like this
112
113    {pygmentize:: xml}
114    <distributionManagement>
115      <site>
116        <id>website.fusesource.org</id>
117        <name>website</name>
118        <url>dav:http://fusesource.com/forge/dav/myproject</url>
119      </site>
120    </distributionManagement>
121    {pygmentize}
122
123    Any of the Maven Wagon transport mechanisms should be supported (file, scp, dav etc).
124  
125    Then to actually deploy the static site to some remote system you can use the following:
126
127        mvn scalate:deploy
128    
129    This will deploy the site generated by the `scalate:sitegen` goal to the website 
130    location you have provided in the `site` area of the `distributionManagement` section of 
131    your `pom.xml`
132
133    If you also want to deploy a regular maven website too then you can reuse the same 
134    site configuration as above but just specify a `remoteDirectory` property on the 
135    plugin (which defaults to ".." to avoid including the maven project name in the deploy url)
136    
137    You will need to add the project's Web server to your Maven configuration:
138    
139    {pygmentize:: xml}
140    <server>
141      <id>website.fusesource.org</id>
142      <username>xxxx</username>
143      <password>xxxxx</password>
144    </server>
145    {pygmentize}
146
147.left
148  :markdown
149    <h1 id="linkCheck">Link Checking</h1>
150
151.right
152  :markdown
153
154    Its easy to make a mistake in your wiki files and create a bad link. So we have a 
155    linkcheck report you can add to your pom.xml if you want to generate a report of any bad 
156    links that are created as part of your statically generated HTML. 
157
158    Just add the following to your `pom.xml` and you'll get a nice LinkCheck report.
159
160    {pygmentize:: xml}
161    <reporting>
162      <plugins>
163        <plugin>
164          <groupId>org.fusesource.scalate</groupId>
165          <artifactId>maven-scalate-plugin_#{scala_compat_tag}</artifactId>
166          <version>${project_version}</version>
167        </plugin>
168      </plugins>
169    </reporting>
170    {pygmentize}
171
172.left
173  :markdown
174    <h1 id="livereload">Using LiveReload</h1>
175.right
176  :markdown
177  
178    [LiveReload](http://github.com/mockko/livereload) is a tool and a browser plugin for Safari and Chrome. 
179
180        runlivereload
181    
182    LiveReload watches the files on your machine so that as you change a template, CSS or JavaScript 
183    file it will force a reload in the web browser. This means you can sit in your editor changing 
184    files and have a browser window open and you don't have to keep changing focus between the editor 
185    and browser and hitting reload in the browser. You can just hit save in your editor and see the 
186    results in your browser.
187    
188    Or you can use the livereload script directly...
189
190        livereload src
191
192    This works thanks to the `src/.livereload` configuration file knowing about the scalate 
193    template files.
194
195
196.left
197  :markdown
198    <h1 id="export">Exporting Confluence Wikis</h1>
199
200.right
201  :markdown
202  
203    If you have a legacy site you want to port over from Confluence you can run the following command.
204  
205    For example if your Confluence space is called FOO at Apache then the following command will 
206    dump its content as wiki text files...
207
208        scalate confexport --user user --password pass \
209          https://cwiki.apache.org/confluence/rpc/xmlrpc FOO ./out
210
211.left
212  :markdown
213    <h1 id="bootstrapping">Bootstrapping</h1>
214    
215.right
216  :markdown
217  
218    When generating static sites you often need a little bit of bootstrap code 
219    to configure things such that you can configure some filters (for example 
220    the `{snippet}` macros inside Confluence wiki files) which are then setup 
221    and used whether you run Scalate using `mvn jetty:run` for the live website 
222    or use `mvn scalate:sitegen` to generate the static site.
223
224    Thankfully there's a really simple way to add in any custom initialisation 
225    code in Scalate. Just add a class called `scalate.Boot` which should be a 
226    class with a method called `run()` which can then do whatever you need to 
227    configure things before the template engine starts to render your templates 
228    and wiki files.
229
230