@@ -1,10 +1,152 @@
-openvswitch.github.io
-=====================
+# openvswitch.github.io
-Website for Open vSwitch.
+Website for Open vSwitch. This is written in Jekyll. We use:
-Documentation:
+- the templating engine, to format yaml data into html (for the navbar), to use
+ jekyll variables (`page.url`, `site.url`, `page.title`)
-* **\_BUILD**: How to generate the website HTML from Jekyll sources.
-* **\_DOC**: Architecture of the website (layouts, directories, ...).
-* **\_TODO**: Unfinished features and improvements.
+- the layout mechanism. Each page includes only its specific content and
+ declare its layout (which is a html file that contains the logo, the navbar,
+ the footer...)
+
+We do not use:
+
+- blog specific mechanisms: we do not have blogs, we do not have posts. We do
+ not have a `_post/` directory.
+
+## Development
+
+You can develop using `docker-compose`:
+
+ $ docker-compose up
+
+You should see your site at http://localhost:4000/
+
+Alternatively, install the Jekyll dependencies (2.x only, for now), then run:
+
+ $ jekyll server -w
+
+in the main site directory. This will be available at the
+http://localhost:4000/
+
+## Deployment
+
+GitHub pages supports Jekyll without any further changes. To deploy locally,
+run:
+
+ $ jekyll build
+
+in the main site directory. This will output to `_site/`, the contents of which
+can be exported with any static HTTP server.
+
+## Design
+
+### Layouts
+
+The skel (`_layouts/skel.html`) layout contains the header (logo+navbar) and
+the footer. Only the home page uses this.
+
+The page (`_layouts/page.html`) layout "inherits" from the skel layout and adds
+a series of widgets (updates, recent releases, ...) and the title inside the
+mainpage div. Almost every page uses this.
+
+The pagenosidewidget (`_layouts/pagenosidewidget.html`) layout "inherits" from
+the skel layout and adds only the title inside the mainpage div.
+
+The CSS that we use is inspired by the wordpress output (but it's supposed to
+be directly maintainable). It uses heavily fixed sized elements (i.e. we
+explicitly specify the size in px).
+
+Layouts rely on includes
+
+### Includes
+
+We use includes to split html in multiple files. For example the side widgets
+are on `_include/side_widgets.html`.
+
+### Navigation bar
+
+- Style
+
+ The navbar is only a nested series of `<ul><li>` elements (this is in line
+ with current best practices). The navbar display behavior (display/hide
+ submenus) is implemented only in CSS, in a style tag inside header.html. It
+ should support an unlimited number of nested submenus
+
+- Content:
+
+ Jekyll (at least the safe version used by github pages) does not support a
+ way to generate a page list. Therefore we manually list the pages that we
+ want to appear in the navbar (in order) in `_data/nav.yml`. The url attribute
+ is relative to the parent page. A bit of templating magic (recursively
+ including `menulist.html`, with different `include.*` variables) allows us to
+ generate the `<ul><li>` elements
+
+The skel layout includes `_includes/header.html` which includes
+`_includes/menulist.html`.
+
+### Pages
+
+Jekyll allows us to write page content in html or markdown. Most of the pages
+are HTML now, since that is the output of the wordpress importer. Pages that
+require advanced styling (e.g. the homepage) should be in html too.
+
+Currently all the pages use a directory URL (e.g.
+http://openvswitch.org/support/) The page is stored in a file called index.html
+(or index.markdown)
+
+Each page has a yaml preamble that contains the title, the layout that we want,
+and some other information extracted by wordpress that it might be worth
+keeping.
+
+## TODO
+
+- Refine style:
+
+ Test with many browsers
+
+- Navigation summary (under the navbar)
+
+ A > B > C
+
+- There are some TODO in the files. grep for them
+
+- Remove useless info from the preamble? (author, ...)
+
+## Open issues
+
+1) Releases
+
+ This repository currently does not host ovs releases as the oldwebsite did.
+
+ Proposals:
+
+ a) do not host them. Let github generate the files through tags
+
+ + simple
+
+ - Is github reliable? does the file change? Some user might expect it to
+ have a consistent hash
+
+ b) upload them to the website git repository
+
+2) /cgi-bin/man
+
+ There was a script on the old website that generated updated (from master)
+ man pages (in PDF and HTML). There are some links to these pages somewhere
+ on the website. Proposals:
+
+ a) upload static version of the manpages
+
+ - they do not get updated
+
+3) /pipermail/
+
+ `http://openvswitch.org/pipermail` is the mailman archive. If we use github
+ hosting, openvswitch.org will be a CNAME for `openvswitch.github.io` (or
+ something similar). Since we do not have control over
+ `openvswitch.github.io` we cannot redirect `/pipermail/*` to something else.
+
+4) google analytics
+
+ include google analytics snippet
deleted file mode 100644
@@ -1,28 +0,0 @@
-- Install jekyll
-
-Develop the website
--------------------
-
-- Run
- jekyll serve -w
- in the site main directory
-- Go to http://localhost:4000/
-
-Even though jekyll is a static site generator, when run with -w it will
-monitor the source directory for changes and rebuild the website
-automatically.
-
-Deploy the website
-------------------
-
-- Run
- jekyll build
- in the site main directory
-- The output will be in the _site/ subdirectory. It can be exported
- with any static HTTP server
-
-Deploy the website (github pages)
----------------------------------
-
-Github pages support Jekyll. The site source code can be uploaded to a repo
-and it will be automatically compiled and exported.
deleted file mode 100644
@@ -1,78 +0,0 @@
-OVS Jekyll website
-------------------
-
-What we use of jekyll:
- - the templating engine, to format yaml data into html (for the navbar),
- to use jekyll variables (page.url, site.url, page.title)
- - the layout mechanism. Each page includes only its specific content and
- declare its layout (which is a html file that contains the logo,
- the navbar, the footer...)
-What we do not use:
- - blog specific mechanisms: we do not have blogs, we do not have posts.
- We do not have a _post/ directory.
-
-
-Layouts
--------
-
-The skel (_layouts/skel.html) layout contains the header (logo+navbar) and
-the footer. It displays it content into a center ~900px-wide div. It is
-directly used only for the homepage.
-
-The page (_layouts/page.html) layout "inherits" from the skel layout and adds
-a series of widgets (updates, recent releases, ...) and the title inside the
-mainpage div.
-Almost every page uses this.
-
-The pagenosidewidget (_layouts/pagenosidewidget.html.html) layout "inherits"
-from the skel layout and adds only the title inside the mainpage div.
-
-The CSS that we use is inspired by the wordpress output (but it's supposed
-to be directly maintainable). It uses heavily fixed sized elements (i.e. we
-explicitly specify the size in px).
-
-Layouts rely on includes
-
-
-Includes
---------
-
-We use includes to split html in multiple files. For example the side widgets
-are on _include/side_widgets.html.
-
-
-Navigation bar
---------------
-
-- Style:
- The navbar is only a nested series of <ul> <li> elements (this is in line
- with current best practices).
- The navbar display behavior (display/hide submenus) is implemented only in
- CSS, in a style tag inside header.html. It should support an unlimited
- number of nested submenus
-
-- Content:
- Jekyll (at least the safe version used by github pages) does not support
- a way to generate a page list. Therefore we manually list the pages that
- we want to appear in the navbar (in order) in _data/nav.yml. The url
- attribute is relative to the parent page.
- A bit of templating magic (recursively including menulist.html, with
- different include.* variables) allows us to generate the <ul><li> elements
-
-The skel layout includes _includes/header.html which includes
-_includes/menulist.html
-
-
-Pages
------
-
-Jekyll allows us to write page content in html or markdown. Most of the pages
-are HTML now, since that is the output of the wordpress importer. Pages that
-require advanced styling (e.g. the homepage) should be in html too.
-
-Currently all the pages use a directory URL (e.g. http://openvswitch.org/support/)
-The page is stored in a file called index.html (or index.markdown)
-
-Each page has a yaml preamble that contains the title, the layout that we
-want, and some other information extracted by wordpress that it might be worth
-keeping.
deleted file mode 100644
@@ -1,40 +0,0 @@
-TODOS
-
-- Refine style:
- test with many browsers
-
-- Navigation summary (under the navbar) ?
- A > B > C
-
-- There are some TODO in the files. Please grep for them
-
-- Remove useless info from the preamble? (author, ...)
-
-- Remove (or prefix with "_") this TODO file
-
-OPEN ISSUES
-
-1) Releases
- This repository currently does not host ovs releases as the oldwebsite did.
- Proposals:
- a) do not host them. Let github generate the files through tags
- + simple
- - Is github reliable? does the file change? Some user might
- expect it to have a consistent hash
- b) upload them to the website git repository
-
-2) /cgi-bin/man
- There was a script on the old website that generated updated (from master)
- man pages (in PDF and HTML). There are some links to these pages somewhere
- on the website. Proposals:
- a) upload static version of the manpages
- - they do not get updated
-
-3) /pipermail/
- http://openvswitch.org/pipermail is the mailman archive. If we use github
- hosting, openvswitch.org will be a CNAME for openvswitch.github.io
- (or something similar). Since we do not have control over
- openvswitch.github.io we cannot redirect /pipermail/* to something else.
-
-4) google analytics
- include google analytics snippet
More readable. Less weird filenames. Winning. Signed-off-by: Stephen Finucane <stephen@that.guru> --- README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- _BUILD | 28 ----------- _DOC | 78 ------------------------------- _TODO | 40 ---------------- 4 files changed, 149 insertions(+), 153 deletions(-) delete mode 100644 _BUILD delete mode 100644 _DOC delete mode 100644 _TODO