class: inverse, center, middle # Creating a Personal Website (Using Blogdown) ### Hao Ye ### Health Science Center Libraries, University of Florida ### (updated: 2022-07-19) --- # Motivations * You would like a professional-looking website to present yourself. * You don't want to spend time/money designing something completely custom. * You want to use or learn github / blogdown. * You want to make blogposts using R Markdown. --- # Prerequisites This lesson assumes you: * have some familiarity making *repos* and *commits* * know how to synchronize repos from your computer to GitHub Such as via https://uf-repro.github.io/friendly-github-intro/ --- # Learning Outcomes By the end of the workshop, participants will be able to: * create a basic website using Blogdown * host a website on GitHub Pages * describe the workflow for continuous deployment * deploy a Blogdown website using GitHub Actions --- class: inverse, center, middle # Setup --- # Required Packages ```r install.packages(c("usethis" "blogdown", "renv")) ``` These packages and their included dependencies will have all the tools that we need to get started. --- # Git and RStudio RStudio is not required, but does make some steps easier, so I strongly recommend it. If you have not yet configured Git and GitHub for use from within RStudio, check out these guides: * ["Happy Git and GitHub for the useR"](https://happygitwithr.com/) * ["Managing Git(Hub) Credentials"](https://usethis.r-lib.org/articles/git-credentials.html) --- # Install Hugo Hugo is a static site generator that we will use. This code from the blogdown package will install the latest version and make it available to us. ```r blogdown::install_hugo() ``` --- class: inverse, center, middle # Creating a new site --- # Choose a name The address will be https://{username}.github.io/{repo} e.g. for my username `ha0ye` and repo `my-site`, the eventual website address will be https://ha0ye.github.io/my-site/ You can also host at https://{username}.github.io/ - choose `{username}.github.io` as the repo name. --- # New RStudio Project 1. Open RStudio. 2. `File` -> `New Project` 3. Select `New Directory` 4. Use the name previously chosen, set the local directory, and `Create Project`. --- # Create Blogdown Site ```r blogdown::new_site( theme = "hugo-apero/hugo-apero", format = "toml", sample = FALSE, empty_dirs = TRUE) ``` --- # Set `baseURL` Open `config.toml`. There are a number of configuration options here. Right now, set baseURL to the eventual URL of your site. For example: ``` baseURL = "https://ha0ye.github.io/blogdown-demo" ``` --- # Activate renv The `renv` package will capture all the needed packages to build our website and record this information in configuration files that GitHub will use. ```r renv::init() ``` --- # Setup GitHub Actions We need to give GitHub instructions on how to build our website, and there is a premade script for us to use. ```r usethis::use_github_action("blogdown") ``` --- # Commit and Push These commands will enable Git for this project, and then push it to a new repo on GitHub. ```r usethis::use_git() usethis::use_github() ``` --- class: middle, center # Demo --- class: inverse, center, middle # Technical Machinery --- # Hugo Hugo is a **static site generator**. (there are many other applications that do similar things) It combines your content with a set of theme/style files to create a static HTML webpage. *You can create content in markdown, and not worry about styling.* --- # Blogdown The `{{blogdown}}` package combines R Markdown and Hugo. * you can author pages using R Markdown (so you can create code examples) * it uses Hugo, so you have access to any Hugo theme. --- # Blogdown Preview In your website project, you can preview the webpage with ```r blogdown::serve_site() ``` * You can pop out the panel from RStudio to your web browser. * It will re-render when you save changes. --- # GitHub Pages GitHub Pages will host websites from github repos for you, in the `github.io` domain. *GitHub Pages can also render using __Jekyll__, but we are ignoring it for now.* For GitHub Pages to work, we need to specify where the website files are. We choose the `gh-pages` branch, where only the rendered web files will be stored. --- # GitHub Pages Configuration In the GitHub page, navigate to "Settings" <img src="gh-settings.png" title="GitHub Settings page for a repository. The settings tab is circled with a magenta oval and labeled with '1.' in magenta text." alt="GitHub Settings page for a repository. The settings tab is circled with a magenta oval and labeled with '1.' in magenta text." width="70%" /> --- # GitHub Pages Configuration then select "Pages" <img src="gh-settings-pages.png" title="GitHub Settings page fora repository. The 'Pages' menu item on the left is circled with a magenta oval and labeled with '2.' in magenta text." alt="GitHub Settings page fora repository. The 'Pages' menu item on the left is circled with a magenta oval and labeled with '2.' in magenta text." width="70%" /> --- # GitHub Pages Configuration then select the "gh-pages" branch as the source and click "Save". <img src="gh-settings-pages-source.png" title="GitHub Settings page for a repository. In the 'Source' setting, the 'Branch' pulldown menu is open and set to 'gh-pages' and is circled with a magenta oval and labeled with '3.' in magenta text." alt="GitHub Settings page for a repository. In the 'Source' setting, the 'Branch' pulldown menu is open and set to 'gh-pages' and is circled with a magenta oval and labeled with '3.' in magenta text." width="70%" /> --- # GitHub Actions GitHub Actions lets us do workflow automation on GitHub. Our provided script will setup an R environment to build our website, and then put the website files into the `gh-pages` branch. This means, when we update the contents in GitHub, it will render and update the website automatically. --- # Workflow Suggested website workflow: 1. Open the RStudio project for your website. 2. Start live previews with `blogdown::serve_site()` 3. Make changes to the website 4. Commit changes and push to GitHub. --- class: middle, center # Demo --- class: inverse, center, middle # Customization --- # Menus `config.toml` also determines the top-level menu of your website and what the links are. You can customize the links, including adding your own or removing the defaults. See [the doc page](https://hugo-apero-docs.netlify.app/start/site-config/) for more information. --- # Static Files Files that you want accessible to your website, but not processed through Hugo should go in the `/static/` folder. * it is common to put images in `/static/img/`. * The file `/static/img/image.jpg` becomes https://ha0ye.github.io/blogdown-demo/img/image.jpg on the website. --- # Fonts and Colors You can choose from among the theme's built-in fonts and colors by editing `config.toml`. Customization is available, but will require you to go to extra effort to specify the exact colors and fonts to use. See [the doc page](https://hugo-apero-docs.netlify.app/start/site-config/) for more information. --- class: middle, center # Demo --- class: inverse, center, middle # Content --- # Basics The contents of the website are determined by the files in the `content/` folder. Each folder corresponds to a section of the website, and has a page that can be linked. For example, the `about/` folder contains files to create the https://ha0ye.github.io/blogdown-demo/about page. --- # Sections Each section has a `_index.md` file that contains metadata about how the section will be formatted, and sometimes some descriptive text. This information is in a **yaml** section at the top of the markdown file that begins and ends with ``` --- ``` --- # Pages Within each section, individual pages can be individual markdown files, or folders with an `index.md` file. --- # Styling There are built-in layouts that determine how a page is formatted. You can set this in the `layout: ` field in the YAML header. For more info, see the examples in the template or the docs on * [section configuration](https://hugo-apero-docs.netlify.app/start/section-config/) * [page configuration](https://hugo-apero-docs.netlify.app/start/page-config/) --- class: middle, center # Demo --- # Themes * This guide used the Hugo Apéro theme, but many are available! * You can choose a different theme when making a site, or use `blogdown::install_theme()` * more themes can be found at https://themes.gohugo.io/ --- # Custom Domains * You can use an alternative host rather than GitHub Pages. * A common tool is to use Netlify to build the website. - Netlify will assign a random subdomain of the form `*.netlify.com` - You can use a custom domain with Netlify. (Namecheap is a commonly recommended store.) --- # Summary * A combination of tools and platforms can get you up and running with a personal website quickly! - blogdown + GitHub Pages * Customization is possible! (but not always easy) --- # Thanks * Let me know what content you'd like to see * Contact me for additional questions or consultation requests! * Check back in on the libguide for more modules and contact info: - https://guides.uflib.ufl.edu/reproducibility