Xranklin

About

This repo contains the code for the next minor (and, once properly tested, major) version of Franklin.jl. The code has basically been re-written from scratch, and your help is needed to uncover bugs and problems.

Most of what's offered by Franklin is also offered by Xranklin (apart from what's listed in this issue which we should make as precise as possible).

Link to the new docs (under active construction, note that the search won't work, and I'm also aware that the nav does not work well on mobile phone).

How to help test this?

Assumptions:

• you are familiar with Franklin, and already have a website repo that works,
• you're using GitHub and GitHub deployment (if not, it's also great, but you'll be more on your own for now),
• you're using Julia 1.6+
• your editor uses LF (lines end with \n, this is only a concern for you if you're on Windows but if you use a modern editor, it should be the default or easy to set)

Here's a suggested workflow:

1. duplicate an existing Franklin-repo and give me collaborator access to that duplicated repo (to speed up debugging),
2. clone the repo locally, and add Xranklin to your environment with Pkg.add(url="https://github.com/tlienart/Xranklin.jl", rev="main");
3. cd to the repo and do using Xranklin; serve(debug=true), this will generate a lot of output,
4. if you have errors, check the migration points below to see if the error can be quickly fixed, if not, open an issue
   • indicate your OS, Julia version, link to the repo and to the commit that failed if not the latest
   • indicate the patch version of Xranklin,
   • copy paste the error and previous few lines in the issue,
5. assuming things work locally, test the deployment
   • make sure you adjust prepath in config.md
   • create or change the .github/workflows/deploy.yml to the script below
   • check if it deploys successfully (check in the repo settings that Pages consume gh-pages)
6. thoughts, feedback, open an issue
7. thanks a lot!!

Click here to expand the github deploy script

name: Build and Deploy
on:
  push:
    branches:
      - main
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Git checkout
        uses: actions/checkout@v3

      - name: Cache
        uses: actions/cache@v2
        with:
          path: |
                __cache
                ~/.julia
          key: ${{ runner.os }}-franklin-cache-${{ github.sha }}
          restore-keys: ${{ runner.os }}-franklin-cache-

      # Julia
      - name: Install Julia
        uses: julia-actions/setup-julia@v1
        with:
          version: 1.7

      # Website build
      - run: julia -e '
          using Pkg; Pkg.add(url="https://github.com/tlienart/Xranklin.jl", rev="main");
          using Xranklin; build();'

      # Deployment and caching
      - run: touch __site/.nojekyll
      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          BRANCH: gh-pages
          FOLDER: __site

Migration notes

Link to the new docs, the docs are being built so expect rough edges but if you find things that can be added or explained better, please open issues. Don't worry too much about layout issues for now.

Changes:

• page variable definitions, move from @def x = ... to +++ ... +++ blocks (see docs), @def will still work but will not allow multi-line assignments, generally +++...+++ are preferred now
• @delay is removed (it's not required anymore)
• lxfuns now take arguments as hfuns (a list of parameters corresponding to the braces) see this example
• envfuns now take arguments differently, see this example
• Dates is not available by default, you have to explicitly add using Dates in your utils.jl or in your +++...+++ blocks in order to be able to call things like Date(2022,2,1)

This has not yet been migrated and so you shouldn't expect it to work (see also this issue)

• RSS generation
• sitemap generation
• robots generation
• slug
• lunr

Iterative process

It helps to use ignore = ... in your config.md to avoid trying to build your full site at once which will be very helpful in gradually debugging things. For instance you may have something like

ignore = ["posts/", "about/", "foo/bar.md"]

to indicate that the directories posts/ and about/ as well as the file foo/bar.md should be ignored.

Quirks

Now that there's a __cache folder generated alongside the __site folder, add it to your .gitignore file so it doesn't get pushed. So it will look something like this:

__site/
__cache/
.DS_Store  # if you're on macos

---

Dev Notes

Breaking changes from Franklin

• lx_fun now take args as hfuns so lx_foo(p::Vector{String})
• @def do not accept multiline assignments anymore, generally prefer +++...+++ blocks
• hard assumption of LF (i.e. end of lines are \n and not \r\n) (LF Assumption)

Notes

• (LF Assumption) this could be relaxed, not sure how many people would have an issue; also for it to make sense would need to test on a windows box. To relax, update FranklinParser to have a token for \r\n, and update things with occurrences of \n (including the process_line_return function). Potentially having an editor with \r\n will not make things fail (since we'll capture the \n) but it's not tested.

LaTeX

• hyperrefs
• booktabs (for tables)
• csquotes (for blockquotes)

Search

brew install stork-search/stork-tap/stork
# brew info stork

JS lib:

<script src="https://files.stork-search.net/releases/v1.6.0/stork.js"></script>