Repository: sling-site Updated Branches: refs/heads/master 9de648ff4 -> b08c52ab6
Update README Project: http://git-wip-us.apache.org/repos/asf/sling-site/repo Commit: http://git-wip-us.apache.org/repos/asf/sling-site/commit/b08c52ab Tree: http://git-wip-us.apache.org/repos/asf/sling-site/tree/b08c52ab Diff: http://git-wip-us.apache.org/repos/asf/sling-site/diff/b08c52ab Branch: refs/heads/master Commit: b08c52ab646afe1fbc3b201834924204c96248d1 Parents: 9de648f Author: Bertrand Delacretaz <[email protected]> Authored: Fri Sep 29 12:20:45 2017 +0200 Committer: Bertrand Delacretaz <[email protected]> Committed: Fri Sep 29 12:20:45 2017 +0200 ---------------------------------------------------------------------- README.md | 60 +++++++++++++++------------------------------------------- 1 file changed, 15 insertions(+), 45 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/sling-site/blob/b08c52ab/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 10e7d8b..9ce798e 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,35 @@ -# sling-jbake -Experimenting with JBake for the Apache Sling website. +# Apache Sling Website +This repository contains the content of the http://sling.apache.org/ , which moved in September 2017 from +the Apache CMS to this JBake-generated website. -See also https://issues.apache.org/jira/browse/SLING-6955 - -## How to build the site locally +## How to build and stage the site locally Clone this repository, run the below Maven command, http://localhost:8820/ and enjoy. mvn clean package jbake:inline -Djbake.port=8820 -Djbake.listenAddress=0.0.0.0 + +This allows you to experiment with your changes before eventually publishing them. ## How to publish the website Build the site using `mvn clean package` and then sync the `target/sling-site-*` folder to the `asf-site` branch of this Git repository, commit and push that branch. -The ASF's gitpubsub mechanism then synchronizes that content -on the http://sling.apache.org website, usually within a few seconds. +The ASF's gitpubsub mechanism then synchronizes that content to http://sling.apache.org , usually within a few seconds. ## TODO +Here's a rough list of things that need to be done after the 2017 migration to gitpubsub. -### apache.org requirements -* Activate all the required links checked by https://whimsy.apache.org/site/ +We'll use jira tickets for more specific things, this is more an overview. -### Nice to have -* JBake 2.5.x does not support the `[TOC]` macro but apparently that will be available once JBake moves to https://github.com/vsch/flexmark-java , probably in its next version as per [#376](https://github.com/jbake-org/jbake/pull/376). We might wait for that and just mark the TOCs as unsupported for now. +* Activate all the required links that https://whimsy.apache.org/site/ checks * The "last changed by" information at the bottom right side of pages is missing, it was quite useful. The format is like `Rev. 1692085 by rombert on Tue, 21 Jul 2015 11:04:15 +0000` -### Final validation, activation etc. -* Review all pages -* Resync the content with the current Sling website if needed, initially synced at r1798604 and later (September 26th, 2017) resynced to svn revision 1809724 - -### Done -* Fix internal links like `refs.project-information.path` -* Page header and footer, logo etc -* Remove unused assets files and templates (copied from JBake Groovy sample) -* Tables work now, needed the pegdown TABLES extension -* Move images and other files to /assets and convert their links -* Fix references like `refs.authentication-tasks.headers.excerpt` as well as `.title` references -> replace with copies of those titles and excerpts, or use tags to mark and select -* Fix remaining `refs.` links -> those are probably broken anyway -* Test the downloads.cgi page, requires an apache.org setup (INFRA-14390) -> done at https://sling.apache.org/ng/downloads.cgi -* Fix broken tables: the current pegdown parser has troubles with table cells containing special characters, tables containing a single dash for example need to be converted to `(-)` as a workaround. -* Enumerate child pages in documentation/tutorials-how-tos.html and smilar pages -> replaced with a manually generated list. -* Sitemap page -* Left menu layout is now correct -* Breadcrumbs are back. -* The `#!xml` and `#!java` code higlighting macros are not supported, for now they are replaced by HTML comments. - ## JBake and other technotes -* Currently using 2.5.1, see under `/bin`, docs at http://jbake.org/docs/2.5.1 -* Uses https://github.com/sirthias/pegdown for Markdown, syntax info at https://github.com/sirthias/pegdown/blob/master/src/test/resources/MarkdownTest103/Markdown%20Documentation%20-%20Syntax.md , extensions at http://www.decodified.com/pegdown/api/org/pegdown/Extensions.html -* Groovy MarkupTemplateEngine examples at https://github.com/jbake-org/jbake-example-project-groovy-mt , docs for that engine at http://groovy-lang.org/templating.html#_simpletemplateengine -* Other Apache projects using JBake include at least Tamaya (https://github.com/apache/incubator-tamaya-site) and OpenNLP (https://github.com/apache/opennlp-site) and the Incubator is apparently also switching to it. +* Currently using 2.5.1 via the `jbake-maven-plugin`, see under `/bin`, docs at http://jbake.org/docs/2.5.1 +* That version of JBake uses https://github.com/sirthias/pegdown for Markdown, syntax info at https://github.com/sirthias/pegdown/blob/master/src/test/resources/MarkdownTest103/Markdown%20Documentation%20-%20Syntax.md , extensions at http://www.decodified.com/pegdown/api/org/pegdown/Extensions.html +* Using Groovy MarkupTemplateEngine, examples at https://github.com/jbake-org/jbake-example-project-groovy-mt , docs for that engine at http://groovy-lang.org/templating.html#_simpletemplateengine +* Other Apache projects using JBake include at least Tamaya (https://github.com/apache/incubator-tamaya-site) , OpenNLP (https://github.com/apache/opennlp-site) and http://incubator.apache.org . ##Â Useful scripts and commands To find broken links use - wget --spider -r -nd -nv -l 5 http://localhost:8820/ 2>&1 | grep -B1 'broken link' - -To find leftover `refs.` in pages use - - wget -r -nv -l 5 http://localhost:8820/ - find localhost\:8820/ -type f | xargs grep -l 'refs\.' - -To diff the generated HTML, ignoring housekeeping stuff use - - git diff -U0 | grep -v lastmod | grep -v '^---' | grep -v '^+++' | grep -v '^diff' | grep -v '^index' | grep -v '@@' + wget --spider -r -nd -nv -l 5 http://localhost:8820/ 2>&1 | grep -B1 'broken link' \ No newline at end of file
