AI for building websites

Today

• Design a website for your project, build it with the agent, and put it online with GitHub Pages.

Layout of the site

• Decide what your project site looks like before you build it.
• The site is a web page for readers of your policy work. It should not look like the README of your repository.
• There are two ways to start:
  • sketch the home page yourself, on paper or on a screen,
  • find a website or a free template whose layout you like.
• Your group then builds the site from the sketch or the template.

Who reads the site

• Decide who the reader is and what they need first. The U.S. Web Design System, used by federal agencies, puts this first among its design principles: “Start with real user needs.”
• Put the question and the evidence at the top of the page.
• Show the evidence as a figure or a table where you can. A reader takes in a chart faster than a long paragraph.
• Write short sentences in plain words. Digital.gov keeps a plain language guide for government websites.

Figures and tables

• Each figure needs a title that states what it shows, axes with units, and the source and date of the data.
• The figure on the page is the file your script wrote. Do not paste a screenshot.
• The Urban Institute Data Visualization Style Guide is one policy research organization’s rules for charts. The guide itself is a GitHub Pages site.

HTML, CSS, and JavaScript

• A website is a set of files. A web browser reads the files and displays them.
• HTML holds the content and its structure: headings, paragraphs, images, tables, and links. It is the only file type a website needs.
• CSS controls how the content looks: colors, fonts, and layout.
• JavaScript makes a page interactive, for example a menu that filters a chart.
• CSS and JavaScript are optional. A page with HTML alone still works. It just looks plain.
• A site can also include images and data files.
• The agent writes these files. Your job is to read the result in a browser and ask for changes.

Hosting

• Open an HTML file on your own computer, and your browser displays it. Only you can see it.
• For other people to see it, the files must sit on a computer that is always connected to the internet and has an address. That computer is a server. A service that keeps your files on its server is a host.
• A static website sends every visitor the same files. Your project site is a static website.
• A dynamic website runs a program on the server, for example to handle logins, forms, or a database. It needs more than a static host.

Domain names

• A domain name is the address people type, such as hanzhang.xyz.
• Most hosts give you a free address under their own domain, such as username.github.io.
• An address of your own is bought separately from a domain registrar, for a yearly fee. You then point it to your host. Buying a domain and hosting the files are two separate steps.

Three kinds of pages on GitHub

• GitHub Pages is the simplest host for a course project. It is free, and it serves a website straight from a GitHub repository.
• The repository page is the page GitHub makes for every repository, such as github.com/ngreifer/WeightIt.
  • GitHub decides its layout: GitHub’s menus, the list of files, and the README below them.
  • An HTML file in the repository shows up here as code. Open an index.html on this page and you see its source, with no figures.
• GitHub Pages turns the HTML files in a repository into a website. Visitors see your pages as you designed them, with no GitHub menus or file list. There are two kinds of GitHub Pages sites.
  • A project site comes from any repository. Its address is username.github.io/repository. Each repository can have one.
  • A user site comes from one special repository named username.github.io. Its address is username.github.io. Each account has one, and people use it as a personal homepage.

• Open the first two addresses side by side. They come from the same repository.

Limits of GitHub Pages

• It hosts static websites only. A site that needs logins, forms, or a database needs another host.
• The site is public, even when the repository is private.
• On a free GitHub plan, it works only for public repositories. A private repository needs a paid plan, such as GitHub Pro.
• A site may be no larger than 1 GB. It has a soft limit of 100 GB of traffic per month.
• GitHub asks that sites not be used for online businesses or for sensitive transactions such as passwords or credit card numbers.
• A site that outgrows these limits moves to another host. This course does not need one.
• GitHub documentation: GitHub Pages limits →

A project site for your group

• Build a project site from your group repository. Follow your sketch or template.
• The home page has three parts:
  • your policy question, in one sentence,
  • your data source,
  • at least one figure or table that describes your data, such as the years, places, or number of records it covers.
• The site grows with the project. Add your results and the final product later.

Publishing with GitHub Pages

• In the repository settings, GitHub Pages serves the site from the repository’s main folder or from a folder named docs/. Choose the folder that holds your website files.
• Check the files in that folder before you turn it on. Anyone with the address can open them.
• Record the address in the README of your GitHub repository.
• Exchange addresses with another group and give each other feedback on the site in class.
• GitHub documentation on creating a GitHub Pages site →

If you finish early

• Build a user site for yourself in a repository named username.github.io.
• If you own a domain name, point it to your site. Follow GitHub’s documentation on custom domains.

Your project site

• Who is the reader of your site? What do they need to see first?
• Which figure or table tells that reader the most about your data?
• Did AI help you build the site? Show a concrete example.