blog.go

Documentation: golang.org/x/tools/blog

     1  // Copyright 2013 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package blog implements a web server for articles written in present format.
     6  package blog // import "golang.org/x/tools/blog"
     7  
     8  import (
     9  	"bytes"
    10  	"encoding/json"
    11  	"encoding/xml"
    12  	"fmt"
    13  	"html/template"
    14  	"log"
    15  	"net/http"
    16  	"os"
    17  	"path/filepath"
    18  	"regexp"
    19  	"sort"
    20  	"strings"
    21  	"time"
    22  
    23  	"golang.org/x/tools/blog/atom"
    24  	"golang.org/x/tools/present"
    25  )
    26  
    27  var (
    28  	validJSONPFunc = regexp.MustCompile(`(?i)^[a-z_][a-z0-9_.]*$`)
    29  	// used to serve relative paths when ServeLocalLinks is enabled.
    30  	golangOrgAbsLinkReplacer = strings.NewReplacer(
    31  		`href="https://golang.org/pkg`, `href="/pkg`,
    32  		`href="https://golang.org/cmd`, `href="/cmd`,
    33  	)
    34  )
    35  
    36  // Config specifies Server configuration values.
    37  type Config struct {
    38  	ContentPath  string // Relative or absolute location of article files and related content.
    39  	TemplatePath string // Relative or absolute location of template files.
    40  
    41  	BaseURL       string        // Absolute base URL (for permalinks; no trailing slash).
    42  	BasePath      string        // Base URL path relative to server root (no trailing slash).
    43  	GodocURL      string        // The base URL of godoc (for menu bar; no trailing slash).
    44  	Hostname      string        // Server host name, used for rendering ATOM feeds.
    45  	AnalyticsHTML template.HTML // Optional analytics HTML to insert at the beginning of <head>.
    46  
    47  	HomeArticles int    // Articles to display on the home page.
    48  	FeedArticles int    // Articles to include in Atom and JSON feeds.
    49  	FeedTitle    string // The title of the Atom XML feed
    50  
    51  	PlayEnabled     bool
    52  	ServeLocalLinks bool // rewrite golang.org/{pkg,cmd} links to host-less, relative paths.
    53  }
    54  
    55  // Doc represents an article adorned with presentation data.
    56  type Doc struct {
    57  	*present.Doc
    58  	Permalink string        // Canonical URL for this document.
    59  	Path      string        // Path relative to server root (including base).
    60  	HTML      template.HTML // rendered article
    61  
    62  	Related      []*Doc
    63  	Newer, Older *Doc
    64  }
    65  
    66  // Server implements an http.Handler that serves blog articles.
    67  type Server struct {
    68  	cfg       Config
    69  	docs      []*Doc
    70  	redirects map[string]string
    71  	tags      []string
    72  	docPaths  map[string]*Doc // key is path without BasePath.
    73  	docTags   map[string][]*Doc
    74  	template  struct {
    75  		home, index, article, doc *template.Template
    76  	}
    77  	atomFeed []byte // pre-rendered Atom feed
    78  	jsonFeed []byte // pre-rendered JSON feed
    79  	content  http.Handler
    80  }
    81  
    82  // NewServer constructs a new Server using the specified config.
    83  func NewServer(cfg Config) (*Server, error) {
    84  	present.PlayEnabled = cfg.PlayEnabled
    85  
    86  	if notExist(cfg.TemplatePath) {
    87  		return nil, fmt.Errorf("template directory not found: %s", cfg.TemplatePath)
    88  	}
    89  	root := filepath.Join(cfg.TemplatePath, "root.tmpl")
    90  	parse := func(name string) (*template.Template, error) {
    91  		path := filepath.Join(cfg.TemplatePath, name)
    92  		if notExist(path) {
    93  			return nil, fmt.Errorf("template %s was not found in %s", name, cfg.TemplatePath)
    94  		}
    95  		t := template.New("").Funcs(funcMap)
    96  		return t.ParseFiles(root, path)
    97  	}
    98  
    99  	s := &Server{cfg: cfg}
   100  
   101  	// Parse templates.
   102  	var err error
   103  	s.template.home, err = parse("home.tmpl")
   104  	if err != nil {
   105  		return nil, err
   106  	}
   107  	s.template.index, err = parse("index.tmpl")
   108  	if err != nil {
   109  		return nil, err
   110  	}
   111  	s.template.article, err = parse("article.tmpl")
   112  	if err != nil {
   113  		return nil, err
   114  	}
   115  	p := present.Template().Funcs(funcMap)
   116  	s.template.doc, err = p.ParseFiles(filepath.Join(cfg.TemplatePath, "doc.tmpl"))
   117  	if err != nil {
   118  		return nil, err
   119  	}
   120  
   121  	// Load content.
   122  	content := filepath.Clean(cfg.ContentPath)
   123  	err = s.loadDocs(content)
   124  	if err != nil {
   125  		return nil, err
   126  	}
   127  
   128  	err = s.renderAtomFeed()
   129  	if err != nil {
   130  		return nil, err
   131  	}
   132  
   133  	err = s.renderJSONFeed()
   134  	if err != nil {
   135  		return nil, err
   136  	}
   137  
   138  	// Set up content file server.
   139  	s.content = http.StripPrefix(s.cfg.BasePath, http.FileServer(http.Dir(cfg.ContentPath)))
   140  
   141  	return s, nil
   142  }
   143  
   144  var funcMap = template.FuncMap{
   145  	"sectioned": sectioned,
   146  	"authors":   authors,
   147  }
   148  
   149  // sectioned returns true if the provided Doc contains more than one section.
   150  // This is used to control whether to display the table of contents and headings.
   151  func sectioned(d *present.Doc) bool {
   152  	return len(d.Sections) > 1
   153  }
   154  
   155  // authors returns a comma-separated list of author names.
   156  func authors(authors []present.Author) string {
   157  	var b bytes.Buffer
   158  	last := len(authors) - 1
   159  	for i, a := range authors {
   160  		if i > 0 {
   161  			if i == last {
   162  				if len(authors) > 2 {
   163  					b.WriteString(",")
   164  				}
   165  				b.WriteString(" and ")
   166  			} else {
   167  				b.WriteString(", ")
   168  			}
   169  		}
   170  		b.WriteString(authorName(a))
   171  	}
   172  	return b.String()
   173  }
   174  
   175  // authorName returns the first line of the Author text: the author's name.
   176  func authorName(a present.Author) string {
   177  	el := a.TextElem()
   178  	if len(el) == 0 {
   179  		return ""
   180  	}
   181  	text, ok := el[0].(present.Text)
   182  	if !ok || len(text.Lines) == 0 {
   183  		return ""
   184  	}
   185  	return text.Lines[0]
   186  }
   187  
   188  // loadDocs reads all content from the provided file system root, renders all
   189  // the articles it finds, adds them to the Server's docs field, computes the
   190  // denormalized docPaths, docTags, and tags fields, and populates the various
   191  // helper fields (Next, Previous, Related) for each Doc.
   192  func (s *Server) loadDocs(root string) error {
   193  	// Read content into docs field.
   194  	const ext = ".article"
   195  	fn := func(p string, info os.FileInfo, err error) error {
   196  		if err != nil {
   197  			return err
   198  		}
   199  
   200  		if filepath.Ext(p) != ext {
   201  			return nil
   202  		}
   203  		f, err := os.Open(p)
   204  		if err != nil {
   205  			return err
   206  		}
   207  		defer f.Close()
   208  		d, err := present.Parse(f, p, 0)
   209  		if err != nil {
   210  			return err
   211  		}
   212  		var html bytes.Buffer
   213  		err = d.Render(&html, s.template.doc)
   214  		if err != nil {
   215  			return err
   216  		}
   217  		p = p[len(root) : len(p)-len(ext)] // trim root and extension
   218  		p = filepath.ToSlash(p)
   219  		s.docs = append(s.docs, &Doc{
   220  			Doc:       d,
   221  			Path:      s.cfg.BasePath + p,
   222  			Permalink: s.cfg.BaseURL + p,
   223  			HTML:      template.HTML(html.String()),
   224  		})
   225  		return nil
   226  	}
   227  	err := filepath.Walk(root, fn)
   228  	if err != nil {
   229  		return err
   230  	}
   231  	sort.Sort(docsByTime(s.docs))
   232  
   233  	// Pull out doc paths and tags and put in reverse-associating maps.
   234  	s.docPaths = make(map[string]*Doc)
   235  	s.docTags = make(map[string][]*Doc)
   236  	s.redirects = make(map[string]string)
   237  	for _, d := range s.docs {
   238  		s.docPaths[strings.TrimPrefix(d.Path, s.cfg.BasePath)] = d
   239  		for _, t := range d.Tags {
   240  			s.docTags[t] = append(s.docTags[t], d)
   241  		}
   242  	}
   243  	for _, d := range s.docs {
   244  		for _, old := range d.OldURL {
   245  			if !strings.HasPrefix(old, "/") {
   246  				old = "/" + old
   247  			}
   248  			if _, ok := s.docPaths[old]; ok {
   249  				return fmt.Errorf("redirect %s -> %s conflicts with document %s", old, d.Path, old)
   250  			}
   251  			if new, ok := s.redirects[old]; ok {
   252  				return fmt.Errorf("redirect %s -> %s conflicts with redirect %s -> %s", old, d.Path, old, new)
   253  			}
   254  			s.redirects[old] = d.Path
   255  		}
   256  	}
   257  
   258  	// Pull out unique sorted list of tags.
   259  	for t := range s.docTags {
   260  		s.tags = append(s.tags, t)
   261  	}
   262  	sort.Strings(s.tags)
   263  
   264  	// Set up presentation-related fields, Newer, Older, and Related.
   265  	for _, doc := range s.docs {
   266  		// Newer, Older: docs adjacent to doc
   267  		for i := range s.docs {
   268  			if s.docs[i] != doc {
   269  				continue
   270  			}
   271  			if i > 0 {
   272  				doc.Newer = s.docs[i-1]
   273  			}
   274  			if i+1 < len(s.docs) {
   275  				doc.Older = s.docs[i+1]
   276  			}
   277  			break
   278  		}
   279  
   280  		// Related: all docs that share tags with doc.
   281  		related := make(map[*Doc]bool)
   282  		for _, t := range doc.Tags {
   283  			for _, d := range s.docTags[t] {
   284  				if d != doc {
   285  					related[d] = true
   286  				}
   287  			}
   288  		}
   289  		for d := range related {
   290  			doc.Related = append(doc.Related, d)
   291  		}
   292  		sort.Sort(docsByTime(doc.Related))
   293  	}
   294  
   295  	return nil
   296  }
   297  
   298  // renderAtomFeed generates an XML Atom feed and stores it in the Server's
   299  // atomFeed field.
   300  func (s *Server) renderAtomFeed() error {
   301  	var updated time.Time
   302  	if len(s.docs) > 0 {
   303  		updated = s.docs[0].Time
   304  	}
   305  	feed := atom.Feed{
   306  		Title:   s.cfg.FeedTitle,
   307  		ID:      "tag:" + s.cfg.Hostname + ",2013:" + s.cfg.Hostname,
   308  		Updated: atom.Time(updated),
   309  		Link: []atom.Link{{
   310  			Rel:  "self",
   311  			Href: s.cfg.BaseURL + "/feed.atom",
   312  		}},
   313  	}
   314  	for i, doc := range s.docs {
   315  		if i >= s.cfg.FeedArticles {
   316  			break
   317  		}
   318  
   319  		// Use original article path as ID in atom feed
   320  		// to avoid articles being treated as new when renamed.
   321  		idPath := doc.Path
   322  		if len(doc.OldURL) > 0 {
   323  			old := doc.OldURL[0]
   324  			if !strings.HasPrefix(old, "/") {
   325  				old = "/" + old
   326  			}
   327  			idPath = old
   328  		}
   329  
   330  		e := &atom.Entry{
   331  			Title: doc.Title,
   332  			ID:    feed.ID + idPath,
   333  			Link: []atom.Link{{
   334  				Rel:  "alternate",
   335  				Href: doc.Permalink,
   336  			}},
   337  			Published: atom.Time(doc.Time),
   338  			Updated:   atom.Time(doc.Time),
   339  			Summary: &atom.Text{
   340  				Type: "html",
   341  				Body: summary(doc),
   342  			},
   343  			Content: &atom.Text{
   344  				Type: "html",
   345  				Body: string(doc.HTML),
   346  			},
   347  			Author: &atom.Person{
   348  				Name: authors(doc.Authors),
   349  			},
   350  		}
   351  		feed.Entry = append(feed.Entry, e)
   352  	}
   353  	data, err := xml.Marshal(&feed)
   354  	if err != nil {
   355  		return err
   356  	}
   357  	s.atomFeed = data
   358  	return nil
   359  }
   360  
   361  type jsonItem struct {
   362  	Title   string
   363  	Link    string
   364  	Time    time.Time
   365  	Summary string
   366  	Content string
   367  	Author  string
   368  }
   369  
   370  // renderJSONFeed generates a JSON feed and stores it in the Server's jsonFeed
   371  // field.
   372  func (s *Server) renderJSONFeed() error {
   373  	var feed []jsonItem
   374  	for i, doc := range s.docs {
   375  		if i >= s.cfg.FeedArticles {
   376  			break
   377  		}
   378  		item := jsonItem{
   379  			Title:   doc.Title,
   380  			Link:    doc.Permalink,
   381  			Time:    doc.Time,
   382  			Summary: summary(doc),
   383  			Content: string(doc.HTML),
   384  			Author:  authors(doc.Authors),
   385  		}
   386  		feed = append(feed, item)
   387  	}
   388  	data, err := json.Marshal(feed)
   389  	if err != nil {
   390  		return err
   391  	}
   392  	s.jsonFeed = data
   393  	return nil
   394  }
   395  
   396  // summary returns the first paragraph of text from the provided Doc.
   397  func summary(d *Doc) string {
   398  	if len(d.Sections) == 0 {
   399  		return ""
   400  	}
   401  	for _, elem := range d.Sections[0].Elem {
   402  		text, ok := elem.(present.Text)
   403  		if !ok || text.Pre {
   404  			// skip everything but non-text elements
   405  			continue
   406  		}
   407  		var buf bytes.Buffer
   408  		for _, s := range text.Lines {
   409  			buf.WriteString(string(present.Style(s)))
   410  			buf.WriteByte('\n')
   411  		}
   412  		return buf.String()
   413  	}
   414  	return ""
   415  }
   416  
   417  // rootData encapsulates data destined for the root template.
   418  type rootData struct {
   419  	Doc           *Doc
   420  	BasePath      string
   421  	GodocURL      string
   422  	AnalyticsHTML template.HTML
   423  	Data          interface{}
   424  }
   425  
   426  // ServeHTTP serves the front, index, and article pages
   427  // as well as the ATOM and JSON feeds.
   428  func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
   429  	var (
   430  		d = rootData{
   431  			BasePath:      s.cfg.BasePath,
   432  			GodocURL:      s.cfg.GodocURL,
   433  			AnalyticsHTML: s.cfg.AnalyticsHTML,
   434  		}
   435  		t *template.Template
   436  	)
   437  	switch p := strings.TrimPrefix(r.URL.Path, s.cfg.BasePath); p {
   438  	case "/":
   439  		d.Data = s.docs
   440  		if len(s.docs) > s.cfg.HomeArticles {
   441  			d.Data = s.docs[:s.cfg.HomeArticles]
   442  		}
   443  		t = s.template.home
   444  	case "/index":
   445  		d.Data = s.docs
   446  		t = s.template.index
   447  	case "/feed.atom", "/feeds/posts/default":
   448  		w.Header().Set("Content-type", "application/atom+xml; charset=utf-8")
   449  		w.Write(s.atomFeed)
   450  		return
   451  	case "/.json":
   452  		if p := r.FormValue("jsonp"); validJSONPFunc.MatchString(p) {
   453  			w.Header().Set("Content-type", "application/javascript; charset=utf-8")
   454  			fmt.Fprintf(w, "%v(%s)", p, s.jsonFeed)
   455  			return
   456  		}
   457  		w.Header().Set("Content-type", "application/json; charset=utf-8")
   458  		w.Write(s.jsonFeed)
   459  		return
   460  	default:
   461  		if redir, ok := s.redirects[p]; ok {
   462  			http.Redirect(w, r, redir, http.StatusMovedPermanently)
   463  			return
   464  		}
   465  		doc, ok := s.docPaths[p]
   466  		if !ok {
   467  			// Not a doc; try to just serve static content.
   468  			s.content.ServeHTTP(w, r)
   469  			return
   470  		}
   471  		d.Doc = doc
   472  		t = s.template.article
   473  	}
   474  	var err error
   475  	if s.cfg.ServeLocalLinks {
   476  		var buf bytes.Buffer
   477  		err = t.ExecuteTemplate(&buf, "root", d)
   478  		if err != nil {
   479  			log.Println(err)
   480  			return
   481  		}
   482  		_, err = golangOrgAbsLinkReplacer.WriteString(w, buf.String())
   483  	} else {
   484  		err = t.ExecuteTemplate(w, "root", d)
   485  	}
   486  	if err != nil {
   487  		log.Println(err)
   488  	}
   489  }
   490  
   491  // docsByTime implements sort.Interface, sorting Docs by their Time field.
   492  type docsByTime []*Doc
   493  
   494  func (s docsByTime) Len() int           { return len(s) }
   495  func (s docsByTime) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
   496  func (s docsByTime) Less(i, j int) bool { return s[i].Time.After(s[j].Time) }
   497  
   498  // notExist reports whether the path exists or not.
   499  func notExist(path string) bool {
   500  	_, err := os.Stat(path)
   501  	return os.IsNotExist(err)
   502  }
   503
View as plain text