-
Notifications
You must be signed in to change notification settings - Fork 10
static content for http://rcloud.social
att/rcloud.social
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This document describes the organization and build process for the RCloud Web-site.
The document dinstinguished between two different types of site-file.
1) Topic files which are used to contain the content for the topics selected
from the sites main menu. (e.g. Community, Try It!, Gallery, etc)
2) External documentation files which are maintained sepearate from the site and contain
the user guide and release notes for each version of the RCloud distribution.
RCloud Web-site source tree
---------------------------
This table gives the key elemnts of the source tree.
--------------------------------------------------------------------------------------------------
Folder Description
----------------------------- ---------------------------------------------------------------------
community 'Community' topic folder
documentation 'Documentation' topic folder
documentation/doc.mk Each version documentation Makefile.
gallery 'Gallery' topic folder
tryit 'Try It' topic folder
tutorials 'Tutorials' topic folder
css CSS files used by all topics
images Images used by topics
js Global Javascript files used by the global header and footer code
html Common HTML files (header,footer,Pandoc template) used
by all of the topic pages.
html/template.html5 Default Pandoc topic template.
html/head_template.html Pandoc template used to generate the <head> contents for
all topic pages. See the Notes section for more
about this file
html/body_top_template.html HTML used to create the header and navigation controls
for all of the topic pages. Modifying this file will
change the top menu throughout the site.
html/body_bottom_templatehtml HTML used to create the footer for topic pages.
Modifying this file will change the site footer
throughout the site.
favicon.ico Sites favicon
empty.pd An empty file.
body.html <body> content for the site main page (rcloud.social/index.html)
index.css CSS file referenced by rcloud.social/index.html.
topic.mk Makefile template used to generate the topic pages from markdown.
Makefile.mk Makefile used to create rcloud.social/index.html.
Makefile Master make file.
---------------------------------------------------------------------------------------------
Each topic source folder contains a subset of the following source files.
--------------------------------------------------------------------------------
File Description
---------------- ---------------------------------------------------------------
Makefile Topic specific Makefile. This file includes
'topic.mk' in the root source directory. Each topic
however may customize 'topic.mk' by setting variables or
including 'make' commands within it.
index.pd (optional) Topic markdown file used to create 'index.html'
for this topic. If this file does not exist then 'body.html'
must be provided.
body.html (optional) Topic HTML file used to populate the <body></body>
of 'index.html'. If this file does not exist then 'index.pd'
must be provided.
index.css Topic specific CSS file that is referenced from the
header of 'index.html'. Note that this file is not
optional. If no local CSS style is necessary create
a blank CSS file.
template.html5 (optional) Topic specific Pandoc template file.
If this file does not exist then html/index_template.html5
is used as the Pandoc template file.
See 'tutorials' for an example of the use of a topic specific
template file.
index.yaml (Optional) Some topics are simplified by drawing data
from a YAML source. See 'gallery'.
--------------------------------------------------------------------------------
The site build process is responsible for generating the site folder tree,
converting all of the markdown files to HTML, and populating the output tree
with the HTML and auxiliary files (CSS,Javascript, images, etc).
The build process can be broken into two stages. The first stage
builds the topic pages and the second state builds the external documenation.
The topic page build process produces two output files,
'topic/index.html' and 'topic/index.css', for each topic folder.
The external documentation build process produces a user guide
(documentation/doc/x.y/guidocs/doc.html) and release notes
(documentation/doc/x.y/whatnew/doc.html) for each release version.
Where x.y refers to the release version number.
Before building the site pull a current copy of this repository (e.g., git pull); the doc
directory in this repository contains all the markdown documentation files.
~~~~
cd ../path/to/rcloud
git pull
~~~~
Build the site from command line as follows:
~~~~
cd ~/site_src # Where site_src is the folder with the master Makefile.
# OUT_DIR = site output location
# DOC_DIR = path to the external documetation folder. This is the
# folder containing the version folders (e.g. 1.3,1.4, etc)
make OUT_DIR=~/temp/foo DOC_DIR=path/to/rcloud/doc
~~~~
Remove intermediate files (but not output files).
Some intermediate files are left in the source tree and this is a fast way
to delete.
~~~~
make clean
~~~~
Remove intermeditate and output files. Note that this will not delete the
output tree but will remove all files from it.
~~~~
make OUT_DIR=~/temp/foo clean-all
~~~~
Once you run make command it's advisable to try out newly build pages by using any simple web server
like [https://www.linuxjournal.com/content/tech-tip-really-simple-http-server-python]
$ cd $OUT_DIR
$ python -m SimpleHTTPServer
After that type URL [your hostname: 8000] in your browser and RCloud Social web page should show up
Notes
-----
1) The build instructions for each of the the topic pages are contained in
topic/Makefile. Each topic/Makefile is a thin wrapper around topic.mk.
2) The build instructions for the external documention is in documention/doc.mk.
3) The sites main page is built by ./Makefile.mk which, like the topic/Makefiles
is a wrapper around topic.mk.
4) html/*_template.html files are Pandoc template used to generate the header
and footer for all HTML files (topic and external documentation) generated
by the build process. The templates contain references to CSS and Javascript files
contained in ./css and ./js as well as 'href' links to other files in the output tree.
Templates are required to create the this content
because the CSS,Javascript, and 'href' references, must reference the files irregardless of
their own position in the output tree. For example a file in the documentation folder
can reference a CSS folder like this
~~~~
<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css">
~~~~
but a documentation file in ./documenation/doc/1.3/guidocs/doc.html would need to
reference it like this:
~~~~
<link rel="stylesheet" href="../../../../css/bootstrap.min.css" type="text/css">
~~~~
This problem is solved, in topic.mk, and doc.mk by generating intermediate
files (e.g. head.html,body_top.html,body_bottom.html) with the path to the referenced files set according to the
location of the generated HTML file. The generated file is then included in the
final output file using the Pandoc options like `--include-in-header=head.html`.
Releases
No releases published
Packages 0
No packages published