website: Revamp the learn index page.

- Split articles into groups.

- Add notes besides the entry for fundamentals and quick tour.

website/cmd/gensite/main.go

@@ -66,7 +66,7 @@ func main() {
 	allPaths := []string{""}
 
 	// Render a category index.
-	renderCategoryIndex := func(name, prelude, css, js string, articles []articleMeta) {
+	renderCategoryIndex := func(name, prelude, css, js string, groups []group) {
 		// Add category index to the sitemap, without "/index.html"
 		allPaths = append(allPaths, name)
 		// Create directory
@@ -77,7 +77,7 @@ func main() {
 		}
 
 		// Generate index
-		cd := &categoryDot{base, name, prelude, articles, css, js}
+		cd := &categoryDot{base, name, prelude, groups, css, js}
 		executeToFile(categoryTmpl, cd, filepath.Join(catDir, "index.html"))
 	}
 
@@ -100,11 +100,11 @@ func main() {
 		}
 		css := catInDir(srcFile(cat.Name), catConf.ExtraCSS)
 		js := catInDir(srcFile(cat.Name), catConf.ExtraJS)
-		var articles []articleMeta
+		var groups []group
 		if catConf.AutoIndex {
-			articles = catConf.Articles
+			groups = makeGroups(catConf.Articles, catConf.Groups)
 		}
-		renderCategoryIndex(cat.Name, prelude, css, js, articles)
+		renderCategoryIndex(cat.Name, prelude, css, js, groups)
 
 		// Generate articles
 		for _, am := range catConf.Articles {
@@ -132,7 +132,7 @@ func main() {
 		sort.Slice(allArticleMetas, func(i, j int) bool {
 			return allArticleMetas[i].Timestamp > allArticleMetas[j].Timestamp
 		})
-		renderCategoryIndex("all", "", "", "", allArticleMetas)
+		renderCategoryIndex("all", "", "", "", []group{{Articles: allArticleMetas}})
 	}
 
 	// Generate index page. XXX(xiaq): duplicated code with generating ordinary
@@ -153,3 +153,28 @@ func main() {
 		fmt.Fprintf(file, "%s/%s\n", conf.RootURL, p)
 	}
 }
+
+func makeGroups(articles []articleMeta, groupMetas []groupMeta) []group {
+	groups := make(map[int]*group)
+	for _, am := range articles {
+		g := groups[am.Group]
+		if g == nil {
+			g = &group{}
+			if 0 <= am.Group && am.Group < len(groupMetas) {
+				g.groupMeta = groupMetas[am.Group]
+			}
+			groups[am.Group] = g
+		}
+		g.Articles = append(g.Articles, am)
+	}
+	indices := make([]int, 0, len(groups))
+	for i := range groups {
+		indices = append(indices, i)
+	}
+	sort.Ints(indices)
+	sortedGroups := make([]group, len(groups))
+	for i, idx := range indices {
+		sortedGroups[i] = *groups[idx]
+	}
+	return sortedGroups
+}

website/cmd/gensite/model.go

@@ -39,6 +39,7 @@ type categoryConf struct {
 	ExtraCSS  []string
 	ExtraJS   []string
 	Articles  []articleMeta
+	Groups    []groupMeta
 }
 
 // articleMeta represents the metadata of an article, found in a category
@@ -46,6 +47,8 @@ type categoryConf struct {
 type articleMeta struct {
 	Name      string
 	Title     string
+	Note      string
+	Group     int
 	Timestamp string
 	ExtraCSS  []string
 	ExtraJS   []string
@@ -63,6 +66,17 @@ type article struct {
 	LastModified rfc3339Time
 }
 
+// Metadata of a group, found in a category index.toml.
+type groupMeta struct {
+	Intro string
+}
+
+// All information about a group to render it.
+type group struct {
+	groupMeta
+	Articles []articleMeta
+}
+
 type recentArticles struct {
 	articles []article
 	max      int

website/cmd/gensite/render.go

@@ -41,7 +41,7 @@ type categoryDot struct {
 	*baseDot
 	Category string
 	Prelude  string
-	Articles []articleMeta
+	Groups   []group
 	ExtraCSS string
 	ExtraJS  string
 }

website/learn/index.toml

@@ -1,22 +1,38 @@
 autoIndex = true
 
+[[groups]]
+intro = "Start with:"
+
+[[articles]]
+name = "fundamentals"
+title = "Fundamentals"
+note = "if you are new to shells"
+group = 0
+
 [[articles]]
 name = "tour"
 title = "Quick Tour"
+note = "if you have experience with other shells"
 extraCSS = ["tour.css"]
+group = 0
 
-[[articles]]
-name = "fundamentals"
-title = "Fundamentals"
+[[groups]]
+intro = "Advanced topics:"
 
 [[articles]]
 name = "unique-semantics"
-title = "Some Unique Semantics"
+title = "Unique Semantics"
+group = 1
 
 [[articles]]
 name = "effective-elvish"
 title = "Effective Elvish"
+group = 1
+
+[[groups]]
+intro = "Design and history:"
 
 [[articles]]
 name = "faq"
 title = "FAQ"
+group = 2

website/ref/index.toml

@@ -4,10 +4,17 @@ prelude = "prelude"
 [[articles]]
 name = "language"
 title = "Language Specification"
+group = -1
 
 [[articles]]
 name = "command"
 title = "The Elvish Command"
+group = -1
+
+[[groups]]
+intro = """
+Modules in the Elvish standard library:
+"""
 
 [[articles]]
 name = "builtin"

website/style.css

@@ -245,13 +245,12 @@ code, pre {
  * Category content.
  **/
 
-.category-prelude {
-    padding-top: 4%;
-    margin-bottom: -20px;
+#content.category {
+    padding-top: 16px;
 }
 
-.article-list {
-    padding: 4% 0;
+.category-prelude, .group-intro, .article-list {
+    margin-top: 16px;
 }
 
 .article-list > li {

website/template.html

@@ -181,25 +181,31 @@
 
 {{ define "category-content" }}
   {{ $category := .Category }}
-  <div id="content">
-    {{ if ne .Prelude "" }}
-      <div class="category-prelude article">
-        <article class="article">
-          {{ .Prelude }}
-        </article>
-      </div>
+  <div id="content" class="category">
+    {{ if .Prelude }}
+      <article class="category-prelude article">
+        {{ .Prelude }}
+      </article>
     {{ end }}
-    <ul class="article-list">
-      {{ range $article := .Articles }}
-        <li>
-          <a href="{{ rootURL }}/{{ $category }}/{{ $article.Name }}.html"
-             class="article-link">{{ $article.Title }}</a>
-          <span class="article-timestamp">
-            {{ $article.Timestamp }}
-          </span>
-          <div class="clear"></div>
-        </li>
+    {{ range $group := .Groups }}
+      {{ if $group.Intro }}
+        <div class="group-intro">{{ $group.Intro }}</div>
       {{ end }}
-    </ul>
+      <ul class="article-list">
+        {{ range $article := $group.Articles }}
+          <li>
+            <a href="{{ rootURL }}/{{ $category }}/{{ $article.Name }}.html"
+               class="article-link">{{ $article.Title }}</a>
+            {{ if $article.Note }}
+              &mdash; {{ $article.Note }}
+            {{ end }}
+            <span class="article-timestamp">
+              {{ $article.Timestamp }}
+            </span>
+            <div class="clear"></div>
+          </li>
+        {{ end }}
+      </ul>
+    {{ end }}
   </div>
 {{ end }}