More readable. Less weird filenames. Winning. Signed-off-by: Stephen Finucane <step...@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
diff --git a/README.md b/README.md index 27a4b31..3f9952f 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/_BUILD b/_BUILD deleted file mode 100644 index 3bd23c3..0000000 --- a/_BUILD +++ /dev/null @@ -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. diff --git a/_DOC b/_DOC deleted file mode 100644 index 273e186..0000000 --- a/_DOC +++ /dev/null @@ -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. diff --git a/_TODO b/_TODO deleted file mode 100644 index 38a6a29..0000000 --- a/_TODO +++ /dev/null @@ -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 -- 2.9.3 _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
