jekyll-stale-report

README.md

Most instructions you need are inline in staleness-report.md and make-stale-list.sh.

.gitignore

Add stale-list.yml to your .gitignore file so that you don't have to run it manually and commit it. It sits in Jekyll's _data folder.

Build commands

If you want this to be part of the build process, add these commands to your buildfile.

# Don't forget to chmod
./make-stale-list.sh
JEKYLL_ENV=production jekyll build

Local preview

For local preview, put this in a script file.

# Don't forget to chmod
./make-stale-list.sh
bundle exec jekyll serve --livereload

Travis CI

I'm told Travis limits git log to the last 50 commits, making this a pretty useless command to run with Travis. (The point is to see which files are oldest, n'est-ce pas?)

I'm also told you can add this to .travis.yml to get around that limit—and thus bring this command out of its uselessness:

git:
  depth: 9999999

make-stale-list.sh

# Don't forget to chmod this bad boy

# Change these outputs to match your Jekyll configuration
JEKYLL_SOURCE="./_source" # `source` value in your jekyll config file, relative to where you're keeping this script
JEKYLL_DATA="./_source/_data" # location of Jekyll's _data/ folder, relative to this script

# Add this file to your .gitignore
STALE_LIST_OUTPUT="$JEKYLL_DATA/stale-list.yml"

printf "generated: `date`\ncontents:" > $STALE_LIST_OUTPUT
git ls-tree -r --name-only HEAD -- $JEKYLL_SOURCE --relative=$JEKYLL_SOURCE | while read filename; do
  printf "$(git log -1 --format="\n  - committed: %ai\n    author: %an\n    filepath: " -- $filename)$filename"
done >> $STALE_LIST_OUTPUT

staleness-report.md

layout	title
article	Staleness report

This is a list of all pages in the docs and when they were last updated. This list is sorted by date-time to see which docs are the most stale.

{% if site.data.stale-list == false or site.data.stale-list == nil -%}

***** NO LIST GENERATED *****

You're seeing this message because the staleness report didn't run. Make sure your build process runs build.sh.

To get the staleness report offline, clone the logz-docs repo, run preview.sh, and visit this page ({{page.url}}).

{% else %}

{%- comment -%}

• Comma-separated list of collections to exclude from the stale list.
• Anything that isn't a doc (like contributors) should be added to this list.
• Use collection name only, not the folder name.

•     {%- endcomment -%}
  

{%- assign excludedCollections = "contributors,docs-admin,knowledge-base,tags" | split: "," -%}

{%- comment -%}

• Create empty array of table rows

•     {%- endcomment -%}
  

{%- assign tableRows = "" | split: "" -%}

{%- comment -%}

• Loop through pages

•     {%- endcomment -%}
  

{% for p in site.pages -%}

{%- comment -%}

• If this page doesn't have a .md or .html extension, skip to next forloop
• iteration

•     {%- endcomment -%}
  

{%- assign fileExt = p.path | split: "." | last -%} {%- unless fileExt == "md" or fileExt == "html" -%} {%- continue -%} {%- endunless -%}

{%- comment -%}

• Prepend this page's filepath so it can match format in stale-list.yml

•     {%- endcomment -%}
  

{%- assign thisPath = p.path | prepend: "_source/" -%}

{%- comment -%}

• Find record in stale-list.yml that matches the filepath of this page

•     {%- endcomment -%}
  

{%- assign thisRecord = site.data.stale-list.contents | where: "filepath", thisPath | first %} {%- capture thisRow -%} | {{thisRecord.committed}} | {{thisRecord.author}} | {{p.title | default: p.path }} | {% endcapture -%}

{%- comment -%} Convert thisRow to array {%- endcomment -%} {%- assign thisRow = thisRow | split: "%" -%}

{%- comment -%} Add thisRow to end tableRows {%- endcomment -%} {%- assign tableRows = tableRows | concat: thisRow -%} {% endfor %}

{%- comment -%}

• Now loop through collection documents

•     {%- endcomment -%}
  

{% for d in site.documents -%}

{%- comment -%}

• If this collection is in the excludedCollections list, skip to next
• forloop iteration

•     {%- endcomment -%}
  

{%- assign isExcluded = excludedCollections | map: d.collection | join: "" -%} {%- unless isExcluded == "" -%} {%- continue -%} {%- endunless -%}

{%- comment -%}

• Prepend this document's filepath so it can match format in stale-list.yml

•     {%- endcomment -%}
  

{%- assign thisPath = d.path | prepend: "_source/logzio_collections/" -%}

{%- comment -%}

• Find record in stale-list.yml that matches the filepath of this document

•     {%- endcomment -%}
  

{%- assign thisRecord = site.data.stale-list.contents | where: "filepath", thisPath | first %} {%- capture thisRow -%} | {{thisRecord.committed}} | {{thisRecord.author}} | {{d.title}} | {% endcapture -%}

{%- comment -%} Convert thisRow to array {%- endcomment -%} {%- assign thisRow = thisRow | split: "%" -%}

{%- comment -%} Add thisRow to end tableRows {%- endcomment -%} {%- assign tableRows = tableRows | concat: thisRow -%} {% endfor %}

The list

Generated: {{site.data.stale-list.generated}}

date-time	committed by	link
{{tableRows	sort}}

{% endif -%}