Initial step of migration of beeware.org from Lektor to MkDocs #1

kattni · 2025-11-03T06:28:55Z

Migration from Lektor to MkDocs

This PR is the initial step of the migration from Lektor to MkDocs. We have opted to land this as a proof of concept, and intend to finalise the rest of the tasks in subsequent PRs.

Following an audit of the existing site, there have been some changes to content structure.

TODOs for @freakboy3742

Update GitHub sponsors sponsorship levels.
- Update Sponsor page to reflect updated levels (or leave this for me once you've completed the first step).
Vet the text in community/index.md under Where is the BeeWare community?
Update about/branding.md to include formal guidelines for asset usage.
The primary index page layout is overall wider than the rest of the site because that was the only way to include the sidebar within the main content, and have the text be the same 45rem wide that we have for the other text on the site. Look at this and see if it works for you.

Known outstanding tasks before we can go live

Translations:
- Merge existing translation PO files with updated POT file.
- Ensure translation workflow is present in the repo and working properly.
- Initial translation pass through DeepL to get machine translation.
- Set up Read the Docs translations for every language.
- Set up Weblate:
  - Add website repo
  - Identify strings that do not need to be presented for translation.
Branding guidelines:
- Complete set of branding guidelines.
- Update BeeWare logos on branding page to latest.
Header anchors:
- Add explicit anchors to any headers being linked from elsewhere to avoid failures when translating headers.
rumdl:
- Work through issues to get rumdl passing
- Ensure any rules that are conflicting with MkDocs syntax are disabled in pyproject.toml rumdl configuration
Redirects:
- Sort out comprehensive list of necessary redirects
- Add list to configuration.
Docs linting:
- Enable Markdown link checker and PySpelling
- Get both passing
Code linting:
- Set up ruff to lint the Python scripts present in this repo
.readthedocs.yaml
- Remove --build-with-warnings
BeeWare Docs Tools PR #150
- Land this PR before everything goes live.
pyproject.toml
- Restore beeware-docs-tools main branch
tox.ini
- Restore full suite of translation commands
- Remove --build-with-warnings where necessary
- Enable linting tools (as noted above)
DNS updates
- Point beeware.org to Read the Docs

PR Checklist:

All new features have been tested
All new features have been documented
I have read the CONTRIBUTING.md file
I will abide by the code of conduct

freakboy3742

Post generation script looks great! This would work great as-is; a couple of suggestions inline about ways to simplify the code to make long-term maintenance easier.

freakboy3742 · 2026-01-21T04:03:23Z

blog_script/post_generation.py

+def validate_url(url):
+    """
+    Validates a URL.
+
+    NOTE: CHECK YOUR ENTRY. There are edge cases where this will pass with an invalid entry.
+    """
+    try:


Some type annotations and elaboration on what it does do would be helpful here:

Suggested change

def validate_url(url):

"""

Validates a URL.

NOTE: CHECK YOUR ENTRY. There are edge cases where this will pass with an invalid entry.

"""

try:

def validate_url(url: str) -> bool:

"""Validates a URL.

NOTE: CHECK YOUR ENTRY. This does a simple HEAD request check, but only if

you are connected to the internet. There are edge cases where this will

succeed with an invalid entry.

"""

try:

freakboy3742 · 2026-01-21T04:06:01Z

blog_script/post_generation.py

+            return False
+        else:
+            parsing_validated = False
+            while not parsing_validated:


Why is a loop needed here? Since both branches of the if have returns, this can only run through once AFAICT.

freakboy3742 · 2026-01-21T04:07:56Z

blog_script/post_generation.py

+        if choice in post_types:
+            post_type = post_types[choice]
+        else:
+            print("Invalid; you must choose a number from the list.")


This is entirely valid Python; however it might make more sense to write it as a try/except pair (as "invalid" really is the exception):

Suggested change

if choice in post_types:

post_type = post_types[choice]

else:

print("Invalid; you must choose a number from the list.")

try:

post_type = post_types[choice]

except KeyError:

print("Invalid; you must choose a number from the list.")

This is no longer necessary; this code was refactored out.

freakboy3742 · 2026-01-21T04:09:33Z

blog_script/post_generation.py

+    date = datetime.date.today()
+    return {
+        "title": blog_title,
+        "date": date,


This isn't incorrect; but if we're only using date once, we might as well use it inline.

Suggested change

date = datetime.date.today()

return {

"title": blog_title,

"date": date,

return {

"title": blog_title,

"date": datetime.date.today(),

freakboy3742 · 2026-01-21T04:12:18Z

blog_script/post_generation.py

+    event_name = input("Event name: ")
+    event_url = None
+    while event_url is None:
+        event_url_entry = input("Event URL: ")
+        if validate_url(event_url_entry):
+            event_url = event_url_entry


Some blank lines could aid readability here, making it clear that there are logical "blocks" of activity.

Suggested change

event_name = input("Event name: ")

event_url = None

while event_url is None:

event_url_entry = input("Event URL: ")

if validate_url(event_url_entry):

event_url = event_url_entry

event_name = input("Event name: ")

event_url = None

while event_url is None:

event_url_entry = input("Event URL: ")

if validate_url(event_url_entry):

event_url = event_url_entry

freakboy3742 · 2026-01-21T04:16:01Z

blog_script/post_generation.py

+    valid_event_end_date = False
+    while not valid_event_end_date:
+        try:
+            event_end_date_input = input("Event end date (e.g. 2026-01-01; leave blank if same as event start date): ") or event_start_date_input
+            event_end_date = datetime.datetime.strptime(event_end_date_input, "%Y-%m-%d").date()
+            valid_event_end_date = True
+        except ValueError:
+            print("Invalid date format. Must be YYYY-DD-MM format.")


The logic here is almost identical to the logic for start date. it would be worth pulling out input_date() as a method that takes a prompt (and optionally, a default value), so that the usage here is event_end_date = input_date("Event end date ...:", event_start_date)

You could do similar refactoring for input_url(); you could possibly even go as far as input_choice where there's a "select item from dictionary" logic.

freakboy3742 · 2026-01-21T04:21:16Z

scripts/new_post.py

+    return content
+
+
+class NoAliasDumper(yaml.SafeDumper):


It would be worth adding a comment here to document what "nonstandard" behavior we're encoding here:

Disabling aliases (YAML's behavior of factoring out any repeated values as constants that are referenced)

Ensuring multiline-strings are output with | syntax

freakboy3742 · 2026-01-21T04:22:57Z

blog_script/post_generation.py

+    Path(Path(__file__).parent.parent / f"docs/en/news/posts/{filename_metadata["date"].year}/{filename_metadata["categories"][0].lower()}").mkdir(parents=True, exist_ok=True)
+    return Path(__file__).parent.parent / f"docs/en/news/posts/{filename_metadata["date"].year}/{filename_metadata["categories"][0].lower()}" / filename


The pathname here is (a) long and (b) shared between these two lines. It would be worth constructing that pathname as a variable (which also gives an opportunity to break the path over multiple lines of code), and then using that variable twice.

freakboy3742 · 2026-01-21T04:23:37Z

scripts/new_post.py

+    if filename.is_file():
+        print("Post already exists.")
+    else:
+        content = yaml.dump(metadata, Dumper=NoAliasDumper, sort_keys=False, width=9999)


Worth documenting inline why the two extra keys are needed.

freakboy3742 · 2026-01-21T04:26:41Z

blog_script/post_generation.py

+        payload = dedent("""\
+        Add blog post introduction here.
+
+        <!-- more -->
+
+        Add blog post content here.""")


I find it helpful to indent "dedented" strings as if it were code - that is, at one level deeper than the surrounding statements. That makes the "scope" of the string clearer:

Suggested change

payload = dedent("""\

Add blog post introduction here.



Add blog post content here.""")

payload = dedent("""\

Add blog post introduction here.



Add blog post content here."""

)

freakboy3742

This is awesome! I've pushed the requested content updates, and some tweaks to the macros and blog script, but this is an incredible effort. Thanks so much - can't wait to see this go live!

freakboy3742 · 2026-01-23T04:02:36Z

blog_script/post_generation.py

+        further_involvement = input("Is the team involved in another way? (y/N): ") or "N"
+        if further_involvement in ["N", "n", "no"]:
+            break


This can be simplified a little, and made more robust; if you check further_involvement[0].upper() == "Y"`, you get a boolean that is only true if you write something that starts with "Y" or "y". Enter, or any variant on "no" will return false.

freakboy3742 · 2026-01-23T04:03:27Z

blog_script/post_generation.py

+def validate_url(url: str) -> bool:
+    """
+    Validates a URL.


This is a minor style thing where PyCharm's default is different; but I've always thought docstrings should be on the line with the quotes.

Suggested change

def validate_url(url: str) -> bool:

"""

Validates a URL.

def validate_url(url: str) -> bool:

"""Validates a URL.

freakboy3742 · 2026-01-23T04:04:08Z

blog_script/post_generation.py

+        # verification when an internet connection is unavailable.
+        parsing_url = urlparse(url)
+        if parsing_url.scheme in ["http", "https"] and parsing_url.netloc != "":
+            print("URL is the correct format, however it has not been validated. Verify it on post creation.")


There's a couple of line-length issues and minor formatting things that I think will get picked up by a ruff pass.

freakboy3742 · 2026-01-23T04:09:27Z

blog_script/post_generation.py

+def generate_file_path(filename_metadata):
+    file_path = f"{re.sub(r"[^\w ]", "", filename_metadata["title"]).lower().replace(" ", "-")}.md"
+    docs_path = f"docs/en/news/posts/{filename_metadata["date"].year}/{filename_metadata["categories"][0].lower()}"
+    Path(Path(__file__).parent.parent / docs_path).mkdir(parents=True, exist_ok=True)


There's no need to wrap this in Path if it's already a Path object;

Since the full .parent.parent/docs_path is what is being re-used, we might as well factor the parent.parent part into docs_path.

freakboy3742 · 2026-01-23T04:12:17Z

blog_script/post_generation.py

+
+
+def generate_entry(metadata, payload):
+    filename = generate_file_path(metadata)


This function is only used once, so it's not really worth factoring out.

freakboy3742 · 2026-01-23T04:20:37Z

scripts/new_post.py

As a user ergonomics thing - making this script scripts/new_post.py, and putting a __init__.py in the folder means you can run it as python -m scripts.new_post.

freakboy3742 · 2026-01-23T05:15:40Z

docs/macros.py

+        organizing_introduction = None
+        attending_introduction = None
+        find_us = None
+        for inv in involvement:
+            if inv["type"] == "organizing":
+                organizing_introduction = dedent(f"""\
+                {attendees(authors, team)} will be organizing [{event.name}]({event.url}), which will happen {event_timeframe}!\n\n
+                """)
+            elif inv["type"] == "attending" or "attending" not in inv["type"]:
+                attending_introduction = dedent(f"""\
+                {attendees(authors, team)} will be attending [{event.name}]({event.url}) {event_timeframe}!\n\n
+                """)
+            else:
+                find_us = f"You can find us throughout {event.name}:\n\n"
+
+        if organizing_introduction:
+            content.append(organizing_introduction)
+        if attending_introduction:
+            content.append(attending_introduction)
+        content.append("\n<!-- more -->\n")
+        content.append(f"{event.description}\n\n")
+        if find_us:
+            content.append(find_us)


I think this block can be simplified a little by pre-computing the list of all involvements, and checking membership of that list.

freakboy3742 · 2026-01-23T05:18:03Z

docs/macros.py

A couple of ruff/line length issues in this file.

kattni added 30 commits November 3, 2025 01:27

Initial build of website; homepage.

ace1dbe

Merge remote-tracking branch 'beeware/main' into tooling/mkdocs

ae5168f

Homepage, Documenation, CI.

bdb7afe

RTD build with warnings.

33e3a4b

Current status.

7aa5e2d

Current state.

cac8011

Current status.

d1725dc

Current status.

dc34cfd

Current status.

ae4da68

Add repository Code of Conduct.

6bf482a

Working with dynamic font sizing disabled.

9a8a6e0

Switch back to docs-tools branch.

6288669

Safari fix.

58cd735

Team layout updated.

3ce5d23

Fixes, updates widths.

030fe9f

Shift sidebar.

1bcc045

Team image padding.

e528bb7

Spacing.

e06a241

Spacing.

2019b06

Spacing.

6721971

Current status.

a341841

Switch back to remote branch.

62ca0e8

Blog updates.

a59183b

Blog fixes.

fc4aacc

Current status.

41137a0

Add blog content.

fb08013

Clean up blog content.

8837725

Update authors, add latest blog post.

7991daa

Blog updates, more content.

3511235

About content added.

6a97de7

kattni added 4 commits January 19, 2026 21:50

Not building.

5f13bfd

Post macros and generation script.

21c43a4

Authors links fix.

2895273

Maybe an actual fix.

175dc01

freakboy3742 requested changes Jan 21, 2026

View reviewed changes

kattni added 8 commits January 21, 2026 00:30

Ok no seriously, an actual fix.

335f96c

Update team image links.

42b5074

Address post_generation review; fix authors paths.

c62518f

Clean up macros, build without warnings.

d930bab

rumdl reflow.

4c968ba

rumdl newline after frontmatter

964c3ad

Final additions to current status.

60a05e6

Update image link.

22c4448

kattni changed the title ~~Initial build of website; homepage.~~ Initial step of migration of beeware.org from Lektor to MkDocs Jan 23, 2026

kattni requested a review from freakboy3742 January 23, 2026 01:43

Final config updates.

dc6ad2f

kattni marked this pull request as ready for review January 23, 2026 02:16

kattni and others added 5 commits January 22, 2026 23:04

Update from review.

e4ee700

Minor cleanups on scripts.

bb97d6d

Minor cleanups to macros.

75089da

Revert docs-tools install reference.

00b8f8e

Finish pronouns.

a7c32e5

kattni mentioned this pull request Jan 23, 2026

Final steps for shifting beeware.org to MkDocs #4

Open

25 tasks

kattni and others added 5 commits January 23, 2026 02:48

Add pronouns to team page.

c64c72c

Initial branding guidelines.

cdd0769

Tweak author short names.

162e0c1

Fill in some TODO text.

61da002

Update membership details.

04089d6

freakboy3742 approved these changes Jan 23, 2026

View reviewed changes

kattni merged commit c78a350 into beeware:main Jan 23, 2026
1 check passed

		Path(Path(__file__).parent.parent / f"docs/en/news/posts/{filename_metadata["date"].year}/{filename_metadata["categories"][0].lower()}").mkdir(parents=True, exist_ok=True)
		return Path(__file__).parent.parent / f"docs/en/news/posts/{filename_metadata["date"].year}/{filename_metadata["categories"][0].lower()}" / filename



		def generate_entry(metadata, payload):
		filename = generate_file_path(metadata)

Uh oh!

Initial step of migration of beeware.org from Lektor to MkDocs #1

Initial step of migration of beeware.org from Lektor to MkDocs #1

Uh oh!

Conversation

kattni commented Nov 3, 2025 • edited by freakboy3742 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Migration from Lektor to MkDocs

TODOs for @freakboy3742

Known outstanding tasks before we can go live

PR Checklist:

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kattni commented Nov 3, 2025 •

edited by freakboy3742

Loading